Overview
An organisation is the top-level controller boundary that sits above workspaces and users. A user may belong to many organisations viauser_organisations, but has exactly one current org on users.organisation_id (the switcher context).
- Team identity — current org drives workspace/session listings, org settings, and new API keys.
- API key ownership — keys are scoped to an
organisation_idso a team’s keys are listed and audited together. - Prompt overrides — each team organisation has its own summary prompt override; every personal organisation shares one. Session-scoped jobs (summarisation, etc.) resolve it from
session.workspace_id → workspaces.organisation_id, not from the user’s current org after a switch.
team organisation is shared. Every real account also has exactly one personal organisation, created at its first login: only its owner is a member, it holds any number of private workspaces, and it can’t be joined, managed, renamed or rebranded (409 for everyone, platform admins included). It is hidden from admin lists and shown as “Personal” in the switcher. Workspace lists show only the current organisation’s workspaces. See User lifecycle.
Recording tenancy: when a session starts, session.workspace_id (and therefore org) is stamped once and stays immutable. Switching current org does not move in-flight recordings, change device.active_session_id, or rewrite device.default_workspace_id.
Data model
Endpoints
List organisations (admin only)
role = admin. Returns 403 Forbidden for all other roles.
Create an organisation (admin only)
slug is derived automatically: lowercased, spaces replaced with -. Returns 409 Conflict if the slug already exists.
Response:
Set public subdomain (admin only)
[a-z0-9-]+ and rejects reserved names (default, staging, innover, 10x100, pr{N}, etc.). Returns 409 Conflict if the subdomain is already assigned to another org.
When set, workspace publish/share links for bundles in that org copy https://{public_subdomain}.kair.is/workspaces/{id}/join?code=… instead of kair.is.
List own organisation memberships
kind and is_current marking users.organisation_id. Each entry also includes has_icon and icon_revision so the org switcher can load logos for all memberships, not only the current org.
Organisation icon
Content-Type from the stored MIME). /me/icon is the caller’s current org. /mine/{organisation_id}/icon works for any org the caller belongs to (403 if not a member, 404 if none uploaded). Query ?v={icon_revision} is a cache buster only.
Switch current organisation
user_organisations). Sets users.organisation_id. Does not touch sessions, devices, or workspace membership. Switch events are recorded in audit_trail on users (and membership changes on user_organisations).
Assign a user to an organisation (admin only)
set_as_current is true (default), also updates users.organisation_id. When false, only adds membership without changing the user’s current org. A personal organisation returns 404.
View own organisation
404 Not Found if the user has no organisation assigned yet.
Relationship to API keys
Every API key has anorganisation_id. When a moderator or admin creates a key:
- The server validates that the supplied
organisation_idmatches the requesting user’s own organisation — cross-org key creation is rejected with400 Bad Request. - The key appears in
GET /api/api-keys/org/{organisation_id}for all moderators/admins in that org.
Relationship to prompt overrides
Overrides are stored incustomer_prompt_overrides against organisation_id; NULL is the default shared by every personal organisation. Each save appends a row and the newest row wins, so a reset (a tombstone row) brings back the system prompt.
Platform admins manage every target. Other moderators see and manage only their current team organisation’s; the personal default and other organisations return
403.