Authentication

All authenticated API requests require a Bearer token in the Authorization header.

$
curl https://api.pyramid-ai.com/api/v2/organization \
>
  -H "Authorization: Bearer pai_live_7fK3aB...xQ2z"

API key format

Keys follow the pattern {prefix}{32_random_chars}:

Keys are environment-scoped. A pai_test_* key will return 401 Unauthorized on the production API, and vice versa.

Key lifecycle

active ──(rotate)──> rotated (24h grace period)
  │
  ├──(revoke)──> revoked (immediate)
  │
  └──(expiry)──> expired (automatic)

• Active — the key accepts requests.
• Rotated — a new key has been issued. The old key remains active for 24 hours, then stops working.
• Revoked — immediately invalidated by an admin.
• Expired — past its expires_at date (if one was set).

Key rotation

When you rotate a key, a new key is generated and the old key enters a 24-hour grace period during which both keys are accepted. This allows you to update your integration without downtime.

Display fingerprint

After creation, keys are displayed as a fingerprint: pai_live_...a3f9. This is safe to use in logs and support tickets. Never log the full key.

Security best practices

• Store keys in environment variables or a secrets manager, never in source code
• Use pai_test_* keys for development and CI pipelines
• Rotate keys periodically and after any suspected compromise
• Monitor the last_used_at timestamp — unused keys should be reviewed
• Each integration should use its own key for independent revocation