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

# API Keys

> Create and manage API keys to authenticate programmatic requests to Demomatic.

API keys let you authenticate requests to Demomatic from your own code, scripts, or integrations — without using session-based auth.

<Info>
  API keys are available on the **starter** and **growth** plans. They are not available on solo or free plans.
</Info>

## Permission levels

Each API key has one of two permission levels:

| Permission   | Access                                                                                          |
| ------------ | ----------------------------------------------------------------------------------------------- |
| `read_only`  | `GET` requests only. Use this for read-only integrations such as dashboards or reporting tools. |
| `all_access` | All HTTP methods. Use this when your integration needs to create or update resources.           |

Grant the minimum permission level your integration requires.

## Create an API key

```bash theme={null}
curl -X POST https://api.demomatic.tech/api_keys \
  -H "Authorization: Bearer <clerk_session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI pipeline key",
    "account_id": 99,
    "permission": "all_access"
  }'
```

Response:

```json theme={null}
{
  "data": {
    "id": 12,
    "name": "CI pipeline key",
    "permission": "all_access",
    "api_key": "dm_...",
    "account_id": 99
  }
}
```

<Warning>
  The full `api_key` value is only returned once, at creation time. Copy it immediately — you cannot retrieve it again.
</Warning>

## Use an API key

Include your key in the `Authorization` header on any `/v1/` endpoint:

```bash theme={null}
curl -H "Authorization: Bearer dm_your_key_here" \
  https://api.demomatic.tech/v1/videos
```

All `/v1/` endpoints accept API key authentication. Standard dashboard endpoints use Clerk session auth instead.

## List your API keys

Retrieve all keys for an account. Key values are not returned in list responses — only metadata:

```bash theme={null}
curl https://api.demomatic.tech/api_keys/99 \
  -H "Authorization: Bearer <clerk_session_token>"
```

Response:

```json theme={null}
{
  "data": [
    { "id": 12, "name": "CI pipeline key", "permission": "all_access", "account_id": 99 },
    { "id": 8,  "name": "Read-only dashboard", "permission": "read_only", "account_id": 99 }
  ]
}
```

## Delete an API key

```bash theme={null}
curl -X DELETE https://api.demomatic.tech/api_keys/12 \
  -H "Authorization: Bearer <clerk_session_token>"
```

Deleting a key immediately revokes it. Any requests using the deleted key will fail.

## Rate limits

API key requests are rate-limited to **100 requests per 2 minutes** per key. If you exceed this limit, the API returns a `429 Too Many Requests` response. Build retry logic with exponential backoff into any integration that makes frequent requests.

## Security best practices

<AccordionGroup>
  <Accordion title="Keep keys out of source control">
    Never commit API keys to a git repository. Store them in environment variables or a secrets manager (e.g. GitHub Actions secrets, AWS Secrets Manager, or a `.env` file excluded by `.gitignore`).
  </Accordion>

  <Accordion title="Use the minimum required permission">
    Create keys with `read_only` permission unless your integration needs to create or modify resources. This limits the blast radius if a key is ever exposed.
  </Accordion>

  <Accordion title="Rotate compromised keys immediately">
    If you suspect a key has been exposed, delete it and create a new one. Update any integrations using the old key before deleting it to avoid downtime.
  </Accordion>

  <Accordion title="Use one key per integration">
    Create a separate key for each service or pipeline that needs API access. This makes it easy to revoke access for one integration without affecting others.
  </Accordion>
</AccordionGroup>