> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chamelio.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Keys

> Organization-wide credentials for trusted server-to-server integrations

An API key is a single credential that grants access to everything in your organization. There is no
per-user or per-resource restriction: any endpoint reachable with the key operates across the whole
organization. Treat a key as a privileged secret.

<Info>
  If your integration is used by more than one person, or a call should never reach data its user
  cannot see, use [OAuth Apps](/api-reference/oauth-apps) instead.
</Info>

## Base URL

```
https://platform.chamelio.ai
```

## Authentication

Include your API key in every request using the `X-API-Key` header:

```bash theme={null}
X-API-Key: ca_your_api_key_here
```

### API Key Format

API keys follow the format `ca_<base64url_encoded_string>`.

Example: `ca_xYz123AbCdEfGhIjKlMnOpQrStUvWxYz`

### Obtaining a key

Generate an API key from the Chamelio web application. The full key value is shown once, at
creation - store it in your secret manager before closing the dialog.

### Verifying a key

```bash theme={null}
curl https://platform.chamelio.ai/users/org-info \
  -H "X-API-Key: ca_your_api_key_here"
```

A `200` response confirms the key is valid and shows which organization it belongs to.

## Authentication Errors

The API returns `401 Unauthorized` with one of the following messages:

| Error                      | Description                                        |
| -------------------------- | -------------------------------------------------- |
| `API key required`         | The `X-API-Key` header is missing from the request |
| `Invalid API key`          | The provided API key does not exist in our system  |
| `API key is inactive`      | The API key has been deactivated                   |
| `API key has been revoked` | The API key has been permanently revoked           |
| `API key has expired`      | The API key has passed its expiration date         |

It returns `403 Forbidden` when the key is valid but the user who created it is no longer an active
member of the organization:

| Error                                    | Description                                                  |
| ---------------------------------------- | ------------------------------------------------------------ |
| `API key owner is inactive or not found` | The user who created the key has been deactivated or removed |

<Warning>
  A key rejected this way is **revoked**, not merely refused. Deactivating a user permanently
  invalidates every API key they created, and reactivating them does not bring the keys back -
  create new ones. Before offboarding someone, check which integrations depend on keys they own.
</Warning>

## Rate Limiting

Requests are rate limited **per API key**, using a one-minute window. Every authenticated response
carries the current state:

| Header                  | Description                              |
| ----------------------- | ---------------------------------------- |
| `X-RateLimit-Limit`     | Requests allowed per minute for this key |
| `X-RateLimit-Remaining` | Requests left in the current window      |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets    |

Once the limit is exceeded the API returns `429 Too Many Requests` with a `Retry-After` header
holding the number of seconds until the window resets:

```json theme={null}
{
  "detail": "Rate limit exceeded"
}
```

Your key's limit is reported as `rate_limit_per_minute` by
[Get Organization Info](/api-reference/endpoint/org-info).

## Attribution

Actions taken with an API key are attributed to the user who created the key. Several endpoints also
accept an explicit `user_email` in the request body to attribute an action to a specific member of
your organization instead.

## Available endpoints

Everything under **API Key Access** in the navigation. Start with:

<Columns cols={2}>
  <Card title="Get Organization Info" icon="building" href="/api-reference/endpoint/org-info">
    Your organization's name, legal entities, and rate limit
  </Card>

  <Card title="Upload Document" icon="upload" href="/api-reference/endpoint/core/upload">
    Upload documents to Core for processing
  </Card>

  <Card title="List Workflows" icon="diagram-project" href="/api-reference/endpoint/workflows/list">
    Every workflow available in your organization
  </Card>

  <Card title="Initiate Workflow" icon="play" href="/api-reference/endpoint/workflows/initiate">
    Start a new workflow task with specified variables
  </Card>
</Columns>

## Security notes

<Warning>
  An API key is organization-wide. Anyone holding it can read and modify any document, workflow, and
  task in your organization. Never ship a key in client-side code, a mobile app, or a browser
  extension - use an OAuth application with a public client for those.
</Warning>

<Tip>
  Issue a separate key per integration. That way you can revoke one integration's access, and read
  its usage, without disrupting the others.
</Tip>