# Authentication

Bearer API keys on every request.

Every request carries an API key in the `Authorization` header.

```
Authorization: Bearer sapi_...
```

Keys start with `sapi_`. Create them in the portal at [platform.simular.ai](https://platform.simular.ai). A key is shown once at creation; store it in a secret manager or an environment variable, never in source.

## Check a key

```bash
curl -s "$SAI_API_URL/v1/agents/auth" \
  -H "Authorization: Bearer $SAI_API_KEY"
```

```json
{ "ok": true, "userId": "3fA9kQ2xYz", "authType": "apiKey" }
```

A missing or revoked key returns `401`.

## Firebase ID tokens

The same endpoints also accept a Firebase ID token from a signed-in Sai session in the `Authorization` header. That is how the portal and the `sai` CLI call the API. Key management under `/v1/account/keys` accepts only a Firebase session; an API key cannot create, list or revoke keys. See [Keys](/documentation/api-reference/keys).

## Who can use a key

- Paid accounts: any live key on the account.
- Free accounts: one key, after phone verification. Before verification, key creation returns `403` with `{ "error": "phone_verification_required" }`. The check reads the sign-in token, so verify the phone first and then sign in; if you verified it just now, sign in again before creating the key.

> **Note**
>
> Free-account keys are available from October 1. Today's staging accepts API keys from paid accounts only.

## Errors

| Status | Meaning                                                                             |
| ------ | ----------------------------------------------------------------------------------- |
| `401`  | No credential, or the key is unknown or revoked.                                    |
| `403`  | The key is valid but the account may not do this (plan, ownership).                 |
| `429`  | A rate limit. See [Billing and limits](/documentation/concepts/billing-and-limits). |

Error bodies are JSON with one `error` string:

```json
{ "error": "Message rate limit exceeded. Maximum 60 messages per hour." }
```