# Authentication and conventions

Desk's open API reads conversations, assist tickets and stats, and writes internal notes on conversations. Desk, the CLI, Orbit and the API all use the same commands with the same permissions. This page covers the rules every endpoint shares; the parameters of each endpoint are in [Conversations](api-conversations.md) and [Tickets, stats and team](api-team.md).

The full endpoint list can also be read from the service, with no sign-in:

```bash
curl "$AILO_BASE_URL/api/openapi.json"
```

## Keys

The API is called with a **personal access key**. In Desk, open **Settings › My keys** and select **New key**:

- The key is shown only once, when you create it. Save it right away.
- It expires after 90 days by default, 365 days at most; each person can have up to 20 at a time.
- It can be **Read-only**: a read-only key can call only the read endpoints, and writing a note is refused.
- A key has exactly your own permissions in this organization. When a member is deactivated, all of their keys stop working.
- When you no longer need it, select **Revoke key** on the same page. Revocation takes effect at once and cannot be undone.

::: warning
A key carries your account's permissions. Never put it in front-end code, a public repository or a chat.
:::

## Authentication

Send the key in a header with every request:

```text
Authorization: Bearer <key>
```

A key is a key ID starting with `ak_`, a dot, then the secret.

## Addresses

Every endpoint starts with your service address and your organization; paths carry no version number:

```text
$AILO_BASE_URL/api/tenants/{tenant_id}/…
```

`tenant_id` is your organization. Anything that belongs to another organization returns `404 not_found`, which does not reveal whether it exists.

## Source

The optional header `x-ailo-via` records where a call came from: `api`, `cli`, `ui` or `copilot`. Without it the call counts as `api`; any other value returns `400`. The activity log shows the source from this value. Calls made with a key cannot use `copilot`.

## Writes and retries

Writes are always `POST`, with this body:

```json
{
  "command_id": "c7f0b2d4-1e3a-4c5b-9d8e-7f6a5b4c3d2e",
  "idempotency_key": "c7f0b2d4-1e3a-4c5b-9d8e-7f6a5b4c3d2e",
  "input": { }
}
```

- `command_id` and `idempotency_key` are both required, 1–200 characters. Generating a UUID for each write works well.
- After a network error, retry with the same `command_id`, `idempotency_key` and content to get the first result back; nothing is written twice.
- The same keys with different content return `409 idempotency_key_reused`.
- Requests with a body need `Content-Type: application/json`.

## Pagination

The conversation list returns 50 per page; other lists return everything at once. When there is another page, `next_cursor` in the response has a value and the `x-ailo-next-cursor` header carries the same one; pass it back as the `cursor` parameter for the next page. On the last page `next_cursor` is `null`.

## Rate limits

| Scope | Limit |
| --- | --- |
| Each key | 600 requests a minute |
| All keys in an organization together | 1200 requests a minute |
| Failed authentication from one address | 30 a minute |

Every authenticated response carries three headers, for whichever of the two scopes is tighter:

| Header | Meaning |
| --- | --- |
| `X-RateLimit-Limit` | This minute's limit |
| `X-RateLimit-Remaining` | Requests left |
| `X-RateLimit-Reset` | When the allowance refills, in Unix seconds |

Past the limit you get `429 rate_limited`, and `Retry-After` gives the number of seconds to wait.

## Errors

On an error the body is `{ "ok": false, "code": "…" }`, sometimes with more fields.

| Status | `code` | When |
| --- | --- | --- |
| 400 | `bad_request` | A parameter is missing or malformed, or one is not recognized; `issues` lists each |
| 401 | `unauthorized` | No key, or the key is invalid, expired or revoked |
| 403 | `permission_denied` | You lack the permission, or a read-only key called a write |
| 404 | `not_found` | It does not exist, or belongs to another organization |
| 409 | `idempotency_key_reused` and others | The write was refused; `code` gives the reason |
| 415 | `unsupported_media_type` | The body is not JSON |
| 429 | `rate_limited` | Too many requests; retry after `Retry-After` |
| 500 | `internal` | The service failed |

`401` does not say which of these it was.

## Related

- [Conversations](api-conversations.md)
- [Tickets, stats and team](api-team.md)
