> ## 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.

# Authentication

> One header, two kinds of credential.

```
Authorization: Bearer <token>
```

<Warning>
  The `Bearer ` prefix is required. A raw token on the header returns `401`.
</Warning>

## 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](/api-keys#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`:

```json theme={null}
{ "error": "API key scope is not authorized for this route" }
```

## Keeping it safe

<Warning>
  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.
</Warning>

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

```bash theme={null}
curl -i "https://app.huechat.ai/core/accounts/$ACCOUNT_ID/conversations?page=1" \
  -H "Authorization: Bearer $HUECHAT_TOKEN"
```

`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`.