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

# Authentication

> Bearer keys, organisation scoping, and the four scopes.

Send the API key as a bearer token on every request:

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

Each key belongs to exactly one organisation, fixed when the key is created. Clients never send an organisation ID and cannot reach another organisation's data: every lookup is scoped to the key's organisation, and IDs from other organisations return `404`.

RaiseGate stores only the SHA-256 hash of the key. Any other `Authorization` scheme (for example `Basic`) returns `401`.

## Scopes

| Scope           | Grants                                                             |
| --------------- | ------------------------------------------------------------------ |
| `tracker:read`  | `GET` tracker entities, signals and alerts                         |
| `tracker:write` | create, enrich, update, pause, delete and refresh tracked entities |
| `leads:read`    | `GET` leads                                                        |
| `leads:write`   | record lead decisions; together with `tracker:write`, track leads  |

A missing scope returns `403 insufficient_scope`. Keys issued by the provisioning script carry all four scopes. A narrower key (for example a read-only reporting key with `tracker:read` and `leads:read`) is created by inserting a `partner_api_keys` row with fewer scopes.

On the MCP server, a tool the key is not allowed to use returns a tool error with `insufficient_scope`. The rest keep working.

## Issuing and revoking keys

```bash theme={null}
npm run partner-api:key -- --org <organisation-slug> --name "Pilot integration" [--expires 2027-01-01T00:00:00Z]
```

The command prints the plaintext key once. Transfer it through a secrets manager, not email or chat.

Revoke a key by setting `revoked_at` on its `partner_api_keys` row. Revoked and expired keys return `401 unauthorized`. `last_used_at` is updated on every authenticated request.

<Tip>
  Use a dedicated key per assistant or agent so usage, limits, and revocation are isolated.
</Tip>