> ## 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 |
| `playbook:read` | Staging and production Playbooks, versions, links, and ready suggestions | Off |
| `playbook:write` | Preview and apply Playbook changes to staging | Off |
| `agent:publish` | Publish the exact current staging version after confirmation and tests | 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.

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

Keep Playbook access separate from production publishing when possible. A key
with `playbook:write` can update staging without changing the production agent.
Add `agent:publish` only when the integration must publish after an explicit
confirmation and successful conversation tests.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.