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.
Two additional flags exist on every user account:
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 flow, not a blanket bypass.
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 viauser_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.
Org admin role
Theorg_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:
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).
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):- 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
memberrow inuser_organisationsand auser_workspacesrow 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.
#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 for the full API reference.
API keys
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 inPUBLIC_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 clientbraid-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.
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
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). Personal-organisation workspaces follow org-leave rules (#197) and are out of scope for workspace self-leave until that ships (#208).
Session summaries (text)
Access to a session’s transcript and summary is granted when any of the following is true:- The user is the session owner (the moderator who ran the session).
- The user is a member or owner of the workspace the session belongs to.
- The user holds an explicit
session_sharesgrant — issued when a session owner accepts a summary access request.
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 asession_shares grant alone is not enough. Access requires one of:
- The user is the session owner.
- The user is the workspace owner.
- Role =
moderatorand the user is a workspace member. - The user holds an explicit
audio_sharesgrant — issued when a session owner accepts an audio access request.
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:
A participant who holds a
summary grant still needs a separate audio grant to hear the audio.
Request lifecycle:
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.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
adminkeeps 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.
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 inaudit_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)
- List and view detail
- Requeue or redo
- 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
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 callPOST /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