---
title: "Authentication"
url: https://docs.aila.fyi/api-reference/authentication
source: https://docs.aila.fyi/llms.txt
---

# Authentication

Every Aila API request needs an organization API key, sent as a Bearer token. Each key has explicit permissions (scopes) that you choose when you create it.

---

## Create an API key

Only organization **Owners** and **Admins** can create and manage keys.

1. In Aila, go to **Settings > Connections** and open **API Keys**.
2. Click **Create API key**.
3. Enter a name (for example, `Production Integration`).
4. Select at least one permission (see below).
5. Optionally set an expiration date.
6. Copy the key. Aila shows the full key only once.

Keys look like `ak_` followed by 64 hex characters.

---

## Use the key
```bash
curl https://app.aila.fyi/api/v1/auth/verify \
  -H "Authorization: Bearer ak_your_key_here"
```
`GET /auth/verify` returns the key's ID and permissions, so it's a good first call.

---

## Permissions

| Permission (UI) | Scope | Allows |
| :--- | :--- | :--- |
| Read Calls | `calls:read` | List calls, read details and transcripts. |
| Write Calls | `calls:write` | Upload (batch), update, and delete calls. |
| Read Contacts | `contacts:read` | List and read contacts. |
| Write Contacts | `contacts:write` | Create and update contacts. |
| Read Loan Files | `loan-files:read` | Read loan files and export MISMO 3.4. |
| Write Loan Files | `loan-files:write` | Update loan files. |
| Read Insights | `insights:read` | Read call insights. |
| Read Metrics | `metrics:read` | Read team metrics. |
| Read Organization | `organizations:read` | Read organization details. |

Give each integration only the scopes it needs.

---

## Delete a key

In **Settings > Connections > API Keys**, click **Delete** next to the key. Requests with that key start failing within about a minute.

---

## Errors

| Status | `code` | Fix |
| :--- | :--- | :--- |
| `401` | `UNAUTHORIZED` / `INVALID_API_KEY` | Check the header format and that the key exists and hasn't expired. |
| `403` | `INSUFFICIENT_PERMISSIONS` | Create a key with the required scope. |
| `429` | `RATE_LIMITED` | Slow down. See [Rate limits](https://docs.aila.fyi/api-reference#rate-limits). |