> ## 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={"theme":{"light":"github-light-default","dark":"vesper"}}
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 (`partner_api_keys.key_hash`), plus its first characters (`key_prefix`) so keys can be told apart. Neither can be used to call the API, and a lost key cannot be recovered: issue a new one. Any other `Authorization` scheme (for example `Basic`) returns `401`.

## Keys act for a member

Each key also acts for one member of its organisation, like a signed-in user in the app:

* The member must belong to the organisation. Removing them from the organisation deletes their keys.
* A key never grants more than its member could do: keys of `viewer` members are read-only, whatever their scopes.
* Over MCP, alerts go to the member's email by default, and `whoami` reports the member.
* Keys created before this rule were assigned to their organisation's only admin, or revoked if there was none. A key without a member returns `401 unauthorized`.

## 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={"theme":{"light":"github-light-default","dark":"vesper"}}
npm run partner-api:key -- --org <organisation-slug> --user <member-email> --name "Pilot integration" [--expires 2027-01-01T00:00:00Z]
```

`--user` must be a member of the organisation; issue one key per person. The command prints the member, their role and 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 person and per assistant or agent so usage, limits, and revocation are isolated.
</Tip>