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

# Access Control

> Who can see what, how to request access, and what admins can do.

## Roles

Every user has one of four platform roles. `participant`, `moderator`, and `admin` are set by a platform admin. `org_admin` is set automatically when a user is granted the `admin` role in a specific organisation's membership table.

| Role | Description |
| - | - |
| `participant` | Default. Can create workspaces, run sessions, and see their own content. |
| `moderator` | Like participant, but also gets audio access to sessions in any workspace they're a member of — without needing an explicit audio grant. |
| `org_admin` | Can review and decide on data-subject deletion requests for their organisation(s). Does **not** grant moderator-level session access or platform admin capabilities. Automatically set when `user_organisations.role = 'admin'`; automatically removed when no such admin memberships remain. |
| `admin` | Full access to the `/admin` area and can navigate the whole platform. Does **not** get a blanket content bypass: to view a specific session's transcript, summary, or audio when they are not a member of its workspace, an admin must use the audited [content-elevation](#content-elevation) flow. |

Two additional flags exist on every user account:

| Flag | Meaning |
| - | - |
| `is_guest` | JWT is scoped to a single workspace. Guest accounts cannot access anything outside that workspace and are disabled when removed from it. Joining as a guest does not add organisation membership, and guest (or any workspace-scoped) tokens get `403` on the organisation member list and member detail. A guest who claims the account (`POST /auth/complete-guest-onboarding`) stays a guest until they click the link mailed to the new address; then they become a full user and join the organisations of the workspaces they were in. Guests cannot change their email or use passkeys. |
| `is_disabled` | Cannot log in. Set by an admin; does not delete data. |

***

## Capability summary

At-a-glance view of what each kind of viewer can do on a session. Detailed rules
are in the sections below; admin content access follows the audited
[content-elevation](#content-elevation) flow, not a blanket bypass.

| Viewer | View summary | View transcript & play audio | Trigger jobs | Edit / delete content | Open workspace page |
| - | :-: | :-: | :-: | :-: | :-: |
| Session owner / workspace owner | ✓ | ✓ | ✓ | ✓ | ✓ |
| Moderator (workspace member) | ✓ | ✓ | ✓ | — | ✓ |
| Participant (workspace member, read-only) | ✓ | audio grant only | — | — | ✓ |
| Participant (`session_shares` grant only) | ✓ | audio grant only | — | — | — |
| Any user (`audio_shares` grant only, no other access) | 403 | — | — | — | — |
| Admin (not a workspace member) | audited elevation only (passkey session; without one, no access) | — | — | — | — |
| Admin (also a workspace member) | ✓ | audio grant only | ✓ | ✓ | ✓ |

An admin who is not a member of a session's workspace sees a slimmed-down shell
(metadata + job health) and must request audited access before any transcript,
summary, or topic content is revealed — read-only, with no editing,
job-triggering, audio playback, or navigation into the workspace.

A user holding only an `audio_shares` grant (without a `session_shares` grant or
workspace membership) cannot open the session page — `GET /api/sessions/{session_id}`
returns **403 Forbidden** for an authenticated non-member (session home shows a
request-access landing) and **401 Unauthorized** when not signed in.

Pure non-members (no workspace membership, no share grant, no elevation path) receive
the same **403** on session GET; expired or missing tokens still receive **401** so
the client can refresh the session JWT.

***

## Organisations

An organisation is the top-level controller boundary for a team. Users may belong to **many** organisations via `user_organisations`; `users.organisation_id` is the **current org** (switcher context). Workspaces and session listings are scoped to the current org; **devices are account-scoped** and always list for the user.

The dashboard shows only workspaces whose organisation equals the current organisation (and their sessions), while other listings still include organisation-less workspaces until #197.

| Action | Who can do it |
| - | - |
| List all organisations | Admin only |
| Create an organisation | Admin only |
| Assign / add org membership | Admin only (`PATCH /users/{id}/organisation`; optional `set_as_current: false`) |
| List a user's memberships | Admin only (`GET /users/{id}/organisations`) |
| List own memberships | Any authenticated user (`GET /organisations/mine`) |
| Switch current org | Any authenticated user (`POST /organisations/switch`) |
| View current org (members, slug) | Any authenticated user (`GET /organisations/me`) |
| Grant / revoke org admin role | Platform admin OR existing org admin (`PATCH /organisations/{id}/members/{user_id}/role`) |
| Review data-subject deletion requests | Org admin or platform admin |
| Create, list & revoke invites | Org admin, or platform admin with MFA; team organisations only (`/organisations/{id}/invites`) |
| Accept an invite | Any signed-in, non-guest account holding the link (email invites: only that address) |

### Org admin role

The `org_admin` platform role is a lightweight capability that allows a user to review data-deletion requests for their organisation. It does **not** grant moderator-level session access, API-key management, or any platform admin privileges.

**Granting org admin:**

```
PATCH /organisations/{organisation_id}/members/{user_id}/role
{ "role": "admin" }
```

Requires: caller is a platform `admin` **or** already holds `org_admin` membership in that organisation.

Effect: sets `user_organisations.role = 'admin'`. If the target user's platform role was `participant`, it is promoted to `org_admin`. Moderator/Admin platform roles are **not** touched.

**Revoking org admin:**

Same endpoint with `{ "role": "member" }`. Fails with `422` if no other admin would remain in the organisation. If the user has no remaining org-admin memberships across all orgs, their platform role is demoted back to `participant` (unless they are a moderator or admin, in which case the platform role is not changed).

**Recording tenancy:** `session.workspace_id` is stamped at recording start and does not change when the user switches org. Summarisation and other session-scoped jobs resolve prompt overrides from the **workspace's org**, not the user's current org.

Organisations have a `name`, a `slug` (lowercase, hyphenated, derived from the name) and a `kind`: `team`, or the one `personal` organisation every real account gets at first login, which only its owner can belong to and whose workspaces can't be shared ([User lifecycle](https://docs.kair.is/flows/user-lifecycle.md)).

Org switches update `users.organisation_id` and are recorded in `audit_trail`. Membership add/remove is audited on `user_organisations`.

### Invites

Org admins invite people from **Settings → Organisation** without a platform admin ([#209](https://github.com/meldtech/kair-voice/issues/209)):

* **Invite link**: anyone signed in who opens it can join. Optional `max_uses`; otherwise unlimited until it expires.
* **Email invite**: single use and bound to that address. If no account exists for the email, one is provisioned (no membership yet) and the email's magic link signs them in and goes straight to the invite.
* **Workspace scope**: an invite can name one workspace of the organisation. Accepting adds a `member` row in `user_organisations` and a `user_workspaces` row for **that workspace only**. Org membership on its own opens no workspace, so an outside reviewer sees only that workspace's sessions.
* **Expiry**: 7 days by default, 1–30 days per invite. Revoking (`DELETE /organisations/{id}/invites/{invite_id}`) stops it immediately.

The token is 32 random bytes and lives only in the link's `#fragment` (`/invite#<token>`), which browsers never send to the server. The UI posts it in the body of `POST /organisation-invites/preview` and `POST /organisation-invites/accept`; `organisation_invites` stores only its SHA-256, and the link is shown once at creation. Accept errors: `404` unknown token, `410` revoked, expired or used up, `403` email invite for another address, `409` already has this access.

**Audit:** `organisation_invites` has a full trigger (correlated by `organisation_id`; `token_hash`, `email` and `updated_at` excluded). Accepting writes, in one transaction attributed to the invitee, the invite update (`use_count`, `accepted_by`, `accepted_at`) plus the `user_organisations` and `user_workspaces` inserts, all trail-audited; the request itself is in `audit_events`.

See [Organisations](https://docs.kair.is/api/organisations.md) for the full API reference.

***

## API keys

| Action | Who can do it |
| - | - |
| Create an API key | `moderator` or `admin` only |
| List own organisation's keys | Moderator or admin (must be in same org) |
| Edit / delete own key | The key's owner |

Participants cannot create API keys; the endpoint returns `401 Unauthorized` for them.

**Scope**: device keys are locked to one workspace; user-created keys are locked to one organisation. A key or OAuth token is rejected (`403`) on requests that target a workspace outside its scope (reads and every write, including recording, track and document routes) — this applies even when the key's owner is a platform admin. The user must own or be a member of the target workspace at key-creation time.

**Permission level**: `read` keys may only make `GET`/`HEAD`/`OPTIONS` requests, plus the query endpoints (`…/hirag-query`, `…/moderator-query`, `…/agentic-query`, `…/emerging-themes`). Any other write returns `403`. Keys stop working as soon as their owner is disabled or erased.

***

## Public endpoints

Every API route requires authentication except the ones listed in `PUBLIC_ROUTES` (`api/crates/api/src/routes/mod.rs`): health, login/registration/magic-link/passkey-login, OAuth token, waitlist signup, the trust page, invite-code-gated workspace/workshop join, the device pairing handshake, and endpoints that authenticate themselves (Recall webhook and stream signatures, the Google calendar OAuth callback, MCP bearer tokens, OAuth discovery documents). A test scans the route sources and fails when a handler without auth is missing from that list.

The login, magic-link, registration, passkey-login, waitlist, guest-join, public-info, device-pairing and OAuth-token endpoints are rate limited per client IP (fixed windows in Redis, see `api/crates/api/src/util/rate_limit.rs`); over-limit requests get `429` with `Retry-After`. Limits fail open if Redis is unavailable, and debug builds (local development) skip limiting entirely.

***

## Braid Desktop REST OAuth

The pre-registered public client `braid-desktop` (PKCE, loopback redirect) can call a fixed set of REST routes with a braid-desktop access token. Tokens carry a space-separated `scope` claim and a workspace picker result (`workspace_ids`). MCP access tokens (`aud` bound to `/api/mcp`) cannot call REST handlers.

| Scope | Unlocks |
| - | - |
| `transcripts:read` | List and read sessions in granted workspaces |
| `transcripts:write` | Create sessions and upload audio or transcripts |
| `meetings:read` | List linked calendar meetings and events |
| `meetings:write` | Connect or disconnect Google Calendar, change meeting-bot auto-join |
| `workspaces:read` | List and read granted bundles |
| `workspaces:write` | Create bundles, pin or unpin granted bundles |
| `context:write` | Upload context documents to granted bundles |

Write scopes do not imply read scopes (for example `meetings:write` alone cannot list meetings). The default consent grant includes both read and write pairs where the desktop app needs them.

If the user linked Braid Desktop before `meetings:write` existed, their refresh token keeps the stored scope until they approve sign-in again. Calendar write routes return `403` until then. Pin requires `workspaces:write`; default grants already include it.

Session JWTs and user API keys are unchanged. `GET /api/calendar/accounts` remains session-only.

***

## Workspaces

| Action | Who can do it |
| - | - |
| See a workspace in their list | Owner or member (or admin) |
| View workspace detail & members | Workspace member, owner, or admin |
| Create a workspace | Any authenticated user |
| Rename / change language | Workspace owner or admin |
| Delete | Workspace owner or admin |
| Add a member | Workspace owner or admin |
| Remove a member | Workspace owner or admin |
| Leave (self) | Any member except the owner, default home workspace, or last moderator or admin member |
| Generate join URL | Workspace member, owner, or admin |
| Rename / delete a session document | The uploader, the workspace owner, or an admin |

Leaving (or being removed, here or from the organisation) deletes the `user_workspaces` row and clears the person's ownership of their sessions in that workspace: `sessions.owner_user_id` becomes null and the old owner moves to `former_owner_user_id`, so they can no longer manage, rename or delete those sessions, nor decide access requests for them, while erasure and export still count the sessions as theirs. It does **not** drop organisation membership (`user_organisations`) on a workspace leave, nor delete sessions, claims, or evidence; quote withdrawal remains a separate flow ([#165](https://github.com/meldtech/kair-voice/issues/165)). **Personal-organisation** workspaces follow org-leave rules ([#197](https://github.com/meldtech/kair-voice/issues/197)) and are out of scope for workspace self-leave until that ships ([#208](https://github.com/meldtech/kair-voice/issues/208)).

***

## Session summaries (text)

Access to a session's transcript and summary is granted when **any** of the following is true:

1. The user is the session owner (the moderator who ran the session).
2. The user is a member or owner of the workspace the session belongs to.
3. The user holds an explicit `session_shares` grant — issued when a session owner accepts a summary access request.

Platform admins are **not** exempt: an admin who is not a member of the session's workspace sees scrubbed placeholders until they request access through the audited [content-elevation](#content-elevation) flow.

> **Admin note:** for non-admin users the check covers both workspace *membership* and workspace *ownership*. For admins the native-access path only checks workspace *membership* (a row in the member table). An admin who is the workspace owner but was never added as a member still sees scrubbed content and must elevate.

***

## Session audio and transcript text

Transcript text is treated as equally sensitive as audio — both are derived directly from the recording. Workspace membership or a `session_shares` grant alone is **not** enough. Access requires one of:

1. The user is the session owner.
2. The user is the workspace owner.
3. Role = `moderator` **and** the user is a workspace member.
4. The user holds an explicit `audio_shares` grant — issued when a session owner accepts an audio access request.

A `session_shares` grant only unlocks the **summary text**, not the transcript or audio.

The same tier applies wherever transcript text appears: job status (`GET /status/{job_id}`), chunk listings (`GET /sessions/{id}/chunks`) and the live moderator feed. Summary-tier viewers still get those responses, with transcript text omitted — the live stream sends them insights and pattern alerts but no transcript segments or excerpts.

Platform admins are **not** exempt: there is no admin bypass in the audio/transcript gate. An admin who is a workspace member but is not the session owner, workspace owner, or does not hold an `audio_shares` grant cannot play audio or read the transcript — they must go through the same access-request flow as any other user.

***

## Content Library audio

Audio uploaded directly to a workspace (not tied to a live session) follows a simpler rule: admin, workspace owner, or workspace member.

***

## Requesting access

### Getting access to a session you can't read

A member of a session's organisation who cannot read the session (or play its audio) can file an access request. The session owner **and the org admins of the session's organisation** receive an email, see it in their `/access-requests` inbox and can accept or deny it (an org admin never decides their own request). Requests for sessions outside your organisation are refused, unless you already belong to the session's workspace.

**What each scope unlocks:**

| Scope | What you get |
| - | - |
| `summary` | Read the session's transcript and summary text |
| `audio` | Play back the session's recorded audio |

A participant who holds a `summary` grant still needs a separate `audio` grant to hear the audio.

**Request lifecycle:**

```
You file request (POST /access-requests, scope: "summary" | "audio")
          ↓
Owner & org admins receive email notification
          ↓
Owner or org admin accepts → grant row created → you gain access immediately
Owner denies  → request closed → you can file a new one if needed
```

Duplicate pending requests for the same session + scope return a conflict error — wait for the owner to decide the existing one first.

### Getting added to a workspace

Contact the workspace owner or an admin. The owner can add you directly from the workspace settings page using your email address. Alternatively, the owner can share a join URL (valid for \~1 hour) for self-service joining, or an org admin can send a workspace-scoped [organisation invite](#invites).

***

## Admin capabilities

All `/admin` routes require `role = admin`. A `403 Forbidden` is returned for everyone else.

### Admin MFA

Admin routes also require a passkey sign-in. A session counts as MFA (`mfa` claim) only when it was established with a passkey and the authenticator verified the user (PIN or biometric). Magic-link sessions are single-factor, so an admin signed in by magic link gets `403 Admin access requires passkey sign-in` on every `/admin` route until they sign in with a passkey. `GET /auth/me` returns `admin_mfa_required: true` in that state so the UI can prompt them. Register a passkey in account settings first.

The flag survives token refresh and step-up verification. Impersonation tokens, guest sessions and OAuth-issued tokens never carry it, so an admin acting through one of those cannot reach `/admin`. API keys are exempt from the passkey requirement.

The passkey requirement applies to platform-admin powers, not only `/admin`. The rule:

* **Passkey session:** the platform `admin` keeps every admin power everywhere: content elevation, the admin bypass on sessions, workspaces, audio, and the other shortcuts.
* **No passkey session:** the admin keeps admin standing only in workspaces they are a member of, with the same powers as above for those workspaces and their sessions. Everywhere else they are an ordinary user (no elevation, no bypass).
* **Organisation-level and global powers** (`/admin`, organisation and data-request routes, prompt overrides, the API-key moderator gate, system workshops, cross-workspace listings) need a passkey session in every case, including inside workspaces.

Organisation admins (`org_admin`, org membership admin) do not need a passkey. API keys are exempt. Only the platform `admin` role is gated.

### Audit log

Every write request (by anyone) and every request by a platform admin or an impersonating admin is recorded in `audit_events`: actor, actor kind, method, path, status and a keyed hash of the client IP — never request or response content. Opaque tokens in paths are redacted; high-frequency device traffic (heartbeats, audio chunk uploads, track status) is skipped. The table is append-only (a trigger rejects updates and deletes of rows younger than two years).

### Account email

`PATCH /me` never changes the email directly. A new address is stored on a magic link (`magic_link_tokens.pending_email`) and the link is mailed to that address; the response keeps the old `email` and returns `pending_email`. Clicking the link applies the address, after checking again (case-insensitively) that no other account uses it. Addresses are stored lowercase. Users hold one magic link at a time, so requesting a login link cancels a pending change. Email changes are refused for guest and impersonation tokens.

### Passkeys

Adding or removing a passkey (`/auth/passkey/register/*`, `DELETE /auth/passkey/credentials/{id}`) needs a passkey (MFA) session, because passkeys decide what counts as MFA. The only exception: a user with no passkeys may enrol their first one from a fresh sign-in (magic link or step-up within the last 10 minutes). Impersonation and guest tokens can never change passkeys.

**Lost passkey:** a user who has lost every passkey signs in by magic link and asks a platform admin. An admin with a passkey session removes all of that user's passkeys with `DELETE /admin/users/{user_id}/passkeys`; the user can then enrol a new one from a fresh sign-in. An admin who loses their own passkeys needs another platform admin to do this.

### Sessions & sign-out

`POST /auth/logout` revokes the browser's refresh-token family (from the `refresh_token` cookie) and clears the cookie. It needs no access token and always returns `200`. Presenting a web refresh token that was rotated less than 30 seconds ago returns `401` without revoking anything (another tab won the race; it re-reads the new token). Older reuse is treated as theft and revokes the whole family. OAuth clients get no grace period.

PR preview origins (`https://prNN.kair.is`) are trusted for CORS, magic-link URLs and passkey ceremonies only outside production.

### Impersonation

`POST /admin/users/{user_id}/impersonate` returns a short-lived access token with an `impersonated_by` claim and no refresh token. Every request made with it is recorded as `impersonating_admin` with the admin's id, and it never counts as a fresh sign-in, so it can't submit or approve data deletion requests.

### Users

* List all users (filter by role or disabled status)
* Disable / re-enable a user account
* Impersonate a user (issues a JWT for their account; useful for debugging)
* Change a user's role, email, display name, or organisation assignment

### Organisations

* List all organisations (`GET /admin/organisations`)
* Create an organisation (`POST /admin/organisations`) — slug is auto-derived from the name
* Assign a user to a team organisation (`PATCH /users/{id}/organisation`); personal organisations are never listed or assignable

### Waitlist

* View waitlist signups
* Approve (sends onboarding email) or reject
* Delete entries, resend approval emails

### Jobs

**Transcription jobs**

* List all transcription jobs platform-wide (paginated, filterable by status)
* View job detail including speaker segments
* Requeue a stuck job or redo it from scratch
* Cancel a running job
* View per-session audio chunks with their transcribed text
* Relabel speaker identifiers (merge/rename; rewrites segment labels)

**Summarisation jobs**

* List and view detail
* Requeue or redo

**Topic graph and pattern synthesis jobs**

* Listed in the admin jobs list (`GET /admin/jobs`) with their type and status
* View a session's topics as the topic graph holds them (`GET /admin/sessions/{session_id}/topic-graph`)

### Sessions (platform-wide)

* `GET /admin/sessions` — lists every session across all workspaces, regardless of ownership. Regular users only see sessions within their own workspaces.

### System & infrastructure

* RabbitMQ queue depths
* Worker health (transcription, summarisation, rag)
* Per-workspace topic graph health (topic, entity, theme and session counts, vector index status)
* Graph search test (vector search over topic embeddings, scoped vs global)
* Recent moderator-agent retrieval activity log

### Configuration

| Config area | Editable by admin |
| - | - |
| Rag (agent model, embedding model) | Yes |
| Summarisation (model, Ollama URL) | Yes |
| Transcription (client: local/Scaleway, model names) | Yes |
| Summary evaluation (judge model, enabled flag, backfill) | Yes |
| Trust page content | Yes |

### Content elevation

Admins normally see scrubbed placeholders instead of raw session content (GDPR default). To view actual transcript or summary text for a specific session, an admin must call `POST /admin/content-elevate` with a written reason. This:

* Writes an audit log entry with the reason and the admin's identity.
* Unlocks content for that session for approximately 30 minutes.

### Benchmarks

* Run transcription / summarisation / indexing benchmarks against reference audio
* View benchmark history

### Prompt overrides

Admins set a summarisation prompt override per team organisation, plus one default shared by every personal organisation. Moderators manage only their current team organisation's. Overrides are versioned; history is kept per target ([Organisations](https://docs.kair.is/api/organisations.md#relationship-to-prompt-overrides)).


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