Scoped API keys

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.

Only account administrators can create, change or revoke keys.

Create a key

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 on every response show where a key stands.

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

Get started

Working with the API

Integrate

Scoped API keys

Create a key

Scopes

Manage keys

Limits per key

​Create a key

​Scopes

​Manage keys

​Limits per key

Create a key

Scopes

Manage keys

Limits per key