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 Settings → Developer → API keys or with POST /api/v2/accounts/{account_id}/api-keys. Recognised by the hc_ prefix. Carries only the scopes you grant, plus its own rate limit, optional IP allowlist and expiry. 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:

​
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 Settings → Developer → API keys; 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.