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

# API Keys

> Create, list, and revoke API keys programmatically.

API keys authenticate every data-plane call. Manage them from the dashboard, or with
these endpoints. Keys belong to your organization and carry its plan and limits.

| Method and path            | What it does                               |
| -------------------------- | ------------------------------------------ |
| `GET /v1/api-keys`         | Lists keys, with prefixes only.            |
| `POST /v1/api-keys`        | Creates a key and returns the secret once. |
| `DELETE /v1/api-keys/{id}` | Revokes a key immediately.                 |

## List keys

```http theme={null}
GET /v1/api-keys
```

```json theme={null}
[
  {
    "id": "key_...",
    "name": "prod-bot",
    "key_prefix": "anona_live_",
    "env": "live",
    "created_at": "...",
    "expires_at": null,
    "status": "active"
  }
]
```

Only `key_prefix` is returned. The full secret is shown once, at creation.

`status` is `active` or `expired`; revoked keys are not listed. `expires_at` is
`null` for a key that never expires.

## Create a key

```http theme={null}
POST /v1/api-keys

{ "name": "prod-bot", "env": "live", "expires_in_days": 90 }
```

| Field             | Type    | Required | Description                                                                  |
| ----------------- | ------- | -------- | ---------------------------------------------------------------------------- |
| `name`            | string  | Yes      | A label to identify the key later.                                           |
| `env`             | string  | Yes      | `"live"` or `"test"`.                                                        |
| `expires_in_days` | integer | No       | Days until the key stops working, 1–3650. Omit for a key that never expires. |

```json theme={null}
{
  "id": "key_...",
  "name": "prod-bot",
  "key_prefix": "anona_live_",
  "env": "live",
  "expires_at": "2026-11-13T09:00:00Z",
  "raw_key": "anona_live_XXXXXXXXXXXXXXXXXXXX"
}
```

<Warning>
  `raw_key` appears in this response only. The secret is stored encrypted and Anona cannot
  show it again. A lost key must be revoked and replaced.
</Warning>

## Revoke a key

```http theme={null}
DELETE /v1/api-keys/{id}
```

Returns `204 No Content`. Revocation is immediate and permanent.

<Note>
  To rotate a key: create the new one, cut traffic over, then revoke the old one. Plan and
  limits come from the organization, so a rotated key keeps exactly the same access.
</Note>

## Expiry

A key created with `expires_in_days` stops working on its own. Until then nothing
changes. Expiry is a deadline, not a reduced level of access.

* **Omitting `expires_in_days` means the key never expires**, which is how every key
  behaved before this option existed. Existing keys are unaffected.
* An expired key is rejected with `401` and the error code **`key_expired`**, distinct
  from `invalid_api_key`. Branch on the code: `key_expired` means rotate,
  `invalid_api_key` means the key was never valid.
* **Expiry cannot be extended.** There is no endpoint to push the date back. Create a
  replacement key and cut traffic over, as with rotation.
* Anona emails the key's owner about a week before the date, so the deadline does not
  arrive unannounced.

<Tip>
  Use a short expiry for anything handed to a third party, a CI job, or a demo. A leaked
  key with a deadline stops being a liability on a date you chose in advance.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    How keys are sent, and how to handle them safely.
  </Card>

  <Card title="Usage" icon="gauge" href="/api-reference/usage">
    Credits and rate limits for the calling key.
  </Card>
</CardGroup>