> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://documents.pyramid-ai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://documents.pyramid-ai.com/_mcp/server.

# Authentication

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

```bash
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}`:

| Prefix      | Environment       | Base URL                     |
| ----------- | ----------------- | ---------------------------- |
| `pai_live_` | Production        | `api.pyramid-ai.com`         |
| `pai_test_` | Staging (sandbox) | `api-staging.pyramid-ai.com` |

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.

> **Warning**
>
> The new key plaintext is shown only once at creation. Store it securely — it cannot be retrieved later.

## 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