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

# Scoped API keys

> Least privilege, per-key limits, zero-downtime rotation.

A scoped key is what you give an integration. Unlike a personal token it can
be limited to a few scopes, throttled on its own, pinned to your servers' IPs
and set to expire.

<Note>
  Only account administrators can create, change or revoke keys.
</Note>

## Create a key

```bash theme={null}
curl -X POST https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/api-keys \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "description": "Read-only access for syncing contacts and conversations",
    "scopes": ["contacts:read", "conversations:read", "messages:read"],
    "rate_limit_rpm": 500,
    "allowed_ips": ["203.0.113.0/24"],
    "expires_at": "2027-01-01T00:00:00Z"
  }'
```

The response carries the full `token` **once**. Store it immediately; later
reads return only the `token_prefix`.

## Scopes

| Scope                                    | Allows                                      |
| ---------------------------------------- | ------------------------------------------- |
| `conversations:read`                     | List, view, search and filter conversations |
| `conversations:write`                    | Create, update, assign, change status, mute |
| `conversations:delete`                   | Delete conversations                        |
| `contacts:read`                          | List, view and search contacts              |
| `contacts:write`                         | Create, update, import and merge contacts   |
| `contacts:delete`                        | Delete contacts                             |
| `messages:read`                          | List messages in a conversation             |
| `messages:write`                         | Send, retry and translate messages          |
| `inboxes:read`                           | List and view inboxes                       |
| `inboxes:write`                          | Create, update and delete inboxes           |
| `teams:read`                             | List teams and members                      |
| `teams:write`                            | Create, update and delete teams             |
| `agents:read`                            | List agents and availability                |
| `ai_agents:read`                         | List AI agents, knowledge sources and stats |
| `ai_agents:write`                        | Create, update, publish and train AI agents |
| `broadcasts:read`                        | List broadcasts and reports                 |
| `broadcasts:write`                       | Create, send and cancel broadcasts          |
| `webhooks:read`                          | List webhook subscriptions                  |
| `webhooks:write`                         | Create, update and delete webhooks          |
| `reports:read`                           | Reports and analytics                       |
| `labels:read` / `labels:write`           | Labels                                      |
| `automations:read` / `automations:write` | Automation rules and macros                 |
| `account:read`                           | Account settings                            |

The picker under **Settings → Developer → API keys** lists every scope the
account can grant, including newer ones for templates, workflows, tickets,
deals and appointments.

## Manage keys

| Action                              | Call                                                          |
| ----------------------------------- | ------------------------------------------------------------- |
| List                                | `GET /api/v2/accounts/{account_id}/api-keys`                  |
| Update scopes, limit, IPs or expiry | `PATCH /api/v2/accounts/{account_id}/api-keys/{key_id}`       |
| Rotate                              | `POST /api/v2/accounts/{account_id}/api-keys/{key_id}/rotate` |
| Revoke                              | `DELETE /api/v2/accounts/{account_id}/api-keys/{key_id}`      |
| Usage log                           | `GET /api/v2/accounts/{account_id}/api-keys/{key_id}/usage`   |

Rotation returns a new `token` for the same key id, so you can swap the
secret in your integration without touching scopes or limits.

## Limits per key

`rate_limit_rpm` accepts 1 to 100,000 requests per minute and defaults to
1,000. The [rate limit headers](/rate-limits) on every response show where a
key stands.

<Tip>
  One key per integration. When a partner or a service is retired, revoking its
  key removes exactly that access and nothing else.
</Tip>