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

# Keys

> Create, list and revoke API keys under /v1/account/keys.

API keys are managed in the portal at [platform.simular.ai](https://platform.simular.ai). The endpoints below are what the portal calls. They accept a Firebase session only: an API key cannot manage keys.

## Limits

| Plan | Live keys | Creation rate |
| - | - | - |
| Free | 1 | 5 per hour |
| Paid | 20 | 5 per hour |

Free accounts must verify a phone number first.

## Create a key

```
POST /v1/account/keys
```

```json theme={null}
{ "name": "ci" }
```

`name` is optional, up to 100 characters.

`201 Created`:

```json theme={null}
{ "key": "sapi_...", "keyId": "k_8Hq", "name": "ci" }
```

`key` is returned once. It is not stored in plaintext and cannot be shown again.

| Status | Body |
| - | - |
| `403` | `{ "error": "phone_verification_required", "message": "Verify a phone number before creating an API key on the free plan. If you just verified it, sign in again so your session carries it." }` |
| `403` | An API key was used instead of a Firebase session. |
| `422` | `{ "error": "API key limit reached. Maximum 20 keys per account. Revoke an existing key first." }` The free plan says `Maximum 1 keys per account`. |
| `429` | `{ "error": "Key generation rate limit exceeded. Maximum 5 keys per hour." }` |

The phone check reads the phone claim on the sign-in token, so the number must be verified before the current sign-in. If you verified it during this session, sign out and back in, then create the key. It is the same verified number the free computer's claim checks.

## List keys

```
GET /v1/account/keys
```

```json theme={null}
{
  "keys": [
    { "keyId": "k_8Hq", "name": "ci", "createdAt": 1790000000000, "lastUsedAt": 1790003600000 },
    { "keyId": "k_2Zp", "name": null, "createdAt": 1789000000000, "lastUsedAt": null }
  ]
}
```

Newest first. Secrets are never listed.

## Revoke a key

```
DELETE /v1/account/keys/{keyId}
```

`204 No Content`. A revoked key fails with `401` on its next use.

| Status | Body |
| - | - |
| `404` | `{ "error": "API key not found." }` |

## From the CLI

The `sai` CLI wraps the same endpoints:

```bash theme={null}
sai key generate --name ci
sai key list
sai key revoke <keyId>
```

<Note>
  Free-account keys and the `phone_verification_required` answer are available from October 1.
</Note>