# API keys

URL: https://docs.router.ezat.io/api-keys

> Create, name, copy and revoke API keys, and set a key's spend limit, model list and expiry.

## When to use this page

Use this page to create or revoke a key, to cap what a key can spend or which models it can call, and to see what happens when a key hits a limit.

## Keys belong to the organization

API keys are made in the dashboard, on the **API keys** page, and belong to the organization that is selected in the top bar. Every key draws on that organization's balance. A key keeps working when the person who created it leaves, until someone revokes it.

| Who | Can |
| --- | --- |
| Owners and admins | Create keys, and revoke any key |
| Members | Create keys, and revoke the keys they created |
| Billing members | See the list of keys, but not create them |

Everyone in the organization sees the list: each key's name, the start and end of the key (`ezat_sk_a1b2…wxyz`), its spend limit, when it was last used, when it was created and its status. Nobody can see a full key after it is created. An organization can have up to 50 active keys.

## Create a key

1. Open **API keys** and choose **Create key**.
2. Fill in the form:

   | Field | What it does | Default |
   | --- | --- | --- |
   | **Name** | A label for you, like `Production`, `Laptop` or `CI`. Name the app, machine or person that will use the key. | Required |
   | **Spend limit** | Turn it on to stop the key once it has spent an amount (USD) in a **Period**: **day**, **month** or **total**. See [Spend limits](#spend-limits). | No limit |
   | **Models** | **All models**, or **Only selected models** and tick the ones the key may call. See [Limit a key to some models](#limit-a-key-to-some-models). | All models |
   | **Expires** | **Never**, **In 30 days**, **In 90 days** or **In 1 year**. After that the key is refused. | Never |

3. Choose **Create key**.
4. The **Save your key** dialog shows the full key. Copy it now and store it safely, for example in a password manager or your secret store. Under **Use it with Claude Code**, the dialog also shows the commands that start Claude Code with this key.
5. Choose **I've saved my key**.

<Callout type="warn" title="Copy the key before you close the dialog">
This is the only time the full key is shown. EZAT Router keeps only a hash, so a lost key can't be recovered: create a new one.
</Callout>

The dashboard can't change a key after it is created. To change a key's limits, create a new key with the settings you want, switch your app to it, and revoke the old one.

## Spend limits

A spend limit stops a key once the amount it has been billed in the period reaches the limit:

| Period | Counts what the key spent | Starts again |
| --- | --- | --- |
| **day** | Since 00:00 UTC today | Every day at 00:00 UTC |
| **month** | Since 00:00 UTC on the 1st of this month | On the 1st of each month, 00:00 UTC |
| **total** | Since the key was created | Never |

- The limit is checked before each request, against what the key has been billed so far. A request that starts under the limit always finishes, so a key can end slightly over its limit.
- Once the limit is reached, requests with the key fail with `402` and error type `billing_error` (in the OpenAI format, `insufficient_quota`). The message names the period and the limit, for example `This API key reached its monthly spend limit of $<amount>`.
- A **day** or **month** key works again when the next period starts. A **total** key stays stopped: create a new key.
- The organization's balance still applies. A key under its limit is still refused when the balance is used up.

## Limit a key to some models

With **Only selected models**, the key can call only the models you ticked:

- `GET /v1/models` (and `GET /openai/v1/models`) with that key lists only those models.
- A request for any other model fails with `403` and error type `permission_error`: `This API key is not allowed to use …`.
- A model's other names work too. Allowing a model allows its `author/model` id and all its aliases (see [Models](https://docs.router.ezat.io/models.md)).

### Preview models

A model can be in preview before it is generally available. Preview models are hidden from `GET /v1/models` and return `404` (`not_found_error`) unless the key has preview access. Preview access isn't a dashboard option; ask support@ezat.io if you need it.

## Requests per minute

Each key can make up to 1,000 requests per minute, counted per calendar minute. Token-counting requests count too. Above that, requests fail with `429` and error type `rate_limit_error` (`This API key exceeded its requests-per-minute limit`) and a `retry-after: 30` header. Wait that many seconds and try again. The limit isn't a dashboard setting; if it is too low for you, contact support@ezat.io. See [Rate limits](https://docs.router.ezat.io/reference/rate-limits.md).

## Revoke a key

1. Open **API keys**.
2. Open the actions menu (**…**) on the key's row and choose **Revoke**.
3. Confirm with **Revoke key**.

Requests with the key fail at once with `401` (`This API key has been revoked`), and revoking can't be undone. The key stays in the list with the status **Revoked**, and its usage stays under **Usage**.

A key past its expiry date shows the status **Expired**, and requests with it fail with `401` (`This API key has expired`).

## For AI agents

1. Only the user can create or revoke keys, in the dashboard at `https://router.ezat.io/keys`. Ask them to create one and put it in an environment variable (`EZAT_API_KEY`); never ask them to paste it into the chat.
2. A key's limits can't be changed after it is created. If a key is too restricted, the user creates a new one.
3. On `402` with a message about the key's spend limit, stop: retrying won't help until the period resets. Tell the user which limit was hit.
4. On `403` `This API key is not allowed to use …`, pick a model from `GET https://api.router.ezat.io/v1/models` with the same key, which lists only the models it may call.
5. On `429`, wait the number of seconds in `retry-after`, then retry.