Authentication

The Perspicium Public API v0 requires an API key on every request, including GET /ping.

Generate a Key

1. Sign in at https://perspicium.com.
2. Go to https://perspicium.com/auth/account.
3. Generate or regenerate your API key.
4. Store the plaintext token immediately.

The API stores keys hashed. The full token is only shown immediately after generation. The account page may show a short prefix later so you can identify the active key.

Rotation Model

Each account has one active API key.

When you regenerate a key:

• A new token is created.
• The old token is deleted.
• Existing scripts using the old token will start receiving invalid_api_key.

Recommended Header

Authorization: ApiKey YOUR_TOKEN

Example:

curl "https://perspicium.com/api/v0/ping" \
  -H "Authorization: ApiKey $PERSPICIUM_API_KEY"

Supported Headers

The API currently accepts three forms:

Header	Status	Example
Authorization: ApiKey <token>	Recommended	Authorization: ApiKey abc123...
Authorization: Bearer <token>	Supported	Authorization: Bearer abc123...
X-API-Key: <token>	Legacy support	X-API-Key: abc123...

Prefer Authorization: ApiKey for new integrations.

Security Practices

• Keep API keys out of Git history.
• Load keys from environment variables or a secrets manager.
• Rotate the key if it has been shared, logged, or committed.
• Use separate runtime environments for development and production when possible.
• Do not embed keys in browser-only code. Route requests through your backend if you are building a public web app.

Authentication Errors

Missing key:

{
  "success": false,
  "error": {
    "code": "missing_api_key",
    "message": "API key required"
  }
}

Invalid key:

{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "API key invalid"
  }
}