Skip to main content
The Bearer prefix is required. A raw token on the header returns 401.

​
Two credentials, one header

Personal access token. Found under Settings → Profile. A 48-character hex string with your full role, no expiry. Good for exploring; rotate it with POST /core/profile/reset_access_token if it ever leaks. Scoped API key. Created by an account admin at Account → Developer API. Recognised by the hc_ prefix. Carries only the scopes selected in HueChat, plus its own rate limit, optional IP allowlist and expiry. Keys are created, rotated, reviewed and revoked in the authenticated HueChat app; those account-management operations are not published in this developer portal. A key works on /core/accounts/{account_id}/… and /api/v2/accounts/{account_id}/… only; it cannot read your profile or open a session. Both go on the same header. The server tells them apart by the prefix.

​
Scope

A personal token acts as you. A scoped key acts as the account, limited to the scopes it was given. When a key lacks a scope the response is 403:
Each API guide names the exact scopes its endpoints need. Scopes are grouped the same way in the HueChat scope picker: Sales and Customer CDP routes accept their dedicated scope (for example quotes:read or cdp:read) or the broader deals:* / contacts:* scope, so keys created before the dedicated scopes existed keep working. Grant new integrations the dedicated scopes only. The scope picker in HueChat is the authoritative list for your account.

​
Keeping it safe

Server-side only. A token in browser code is public the moment the bundle ships, and a personal token can do everything your user can.
Keep it in an environment variable or a secrets manager. Prefer a scoped key with the smallest scope set, an expiry date and an IP allowlist. If one leaks, revoke or rotate it under Account → Developer API; the old value stops working immediately.

​
Checking a token works

200 means the credential is authorized for this request. For 401, check the token and the Authorization: Bearer format. For 403, check that the account ID belongs to the key, its owner still has account access, and the key includes conversations:read.