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

# Authentication and scopes

> Create, store, scope, rotate, and revoke organization API keys.

Hobbes authenticates server-to-server requests with organization-scoped API
keys. Keys begin with `hb_live_` and should be handled like passwords.

## Send a key

Use a Bearer authorization header:

```http theme={null}
Authorization: Bearer hb_live_...
```

If your integration cannot set a Bearer header, use `x-api-key` instead:

```http theme={null}
x-api-key: hb_live_...
```

Do not send both. Bearer authentication takes precedence when both are present.

## Choose scopes

| Scope                | Access                                                              | Default |
| -------------------- | ------------------------------------------------------------------- | ------- |
| `sessions:read`      | Session lists and detailed sales analysis                           | On      |
| `people:read`        | Prospect profiles aggregated across sessions                        | On      |
| `accounts:read`      | Account rollups by registrable email domain                         | On      |
| `analytics:read`     | Aggregate funnel metrics                                            | On      |
| `custom_links:read`  | Custom Links, campaigns, jobs, and item results                     | Off     |
| `custom_links:write` | Create and manage Custom Links and thumbnails; includes read access | Off     |
| `transcripts:read`   | Raw conversation turns                                              | Off     |

Create separate keys for separate integrations. A warehouse export does not
need transcript access, and a transcript processor does not necessarily need
account or metrics access.

Custom Links scopes are not added to existing keys automatically. Create or
rotate to a key that explicitly carries the minimum required scope.

<Warning>
  Transcript text can contain prospect PII. Enable `transcripts:read` only for
  systems that need raw text and apply your normal retention and access rules.
</Warning>

## Rotate a key

1. Create a replacement key with the same minimum scopes.
2. Deploy the replacement to your integration.
3. Confirm successful requests with the replacement key.
4. Revoke the old key in Hobbes.

Revocation takes effect immediately. Keep the old key active only for the
short overlap required to complete the deployment.

## Authentication failures

| Status | Meaning                                        | Action                               |
| ------ | ---------------------------------------------- | ------------------------------------ |
| `401`  | Key is missing, malformed, invalid, or revoked | Check the header and replace the key |
| `403`  | Key is valid but lacks the endpoint's scope    | Create a correctly scoped key        |

Hobbes returns the same organization-safe `404` for resources that do not exist
and resources owned by another organization.