Skip to main content

Overview

An organisation is the top-level controller boundary that sits above workspaces and users. A user may belong to many organisations via user_organisations, but has exactly one current org on users.organisation_id (the switcher context).
  1. Team identity — current org drives workspace/session listings, org settings, and new API keys.
  2. API key ownership — keys are scoped to an organisation_id so a team’s keys are listed and audited together.
  3. 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.
Kinds: a 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)

Returns all organisations on the platform, ordered by name. Response:
Requires role = admin. Returns 403 Forbidden for all other roles.

Create an organisation (admin only)

The slug is derived automatically: lowercased, spaces replaced with -. Returns 409 Conflict if the slug already exists. Response:

Set public subdomain (admin only)

Use an empty string to clear. Validates lowercase [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

Returns every organisation the caller belongs to, Personal first and then team organisations by name, with 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

Returns the uploaded appearance icon as binary (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

Must be a member (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)

Adds membership if missing. When 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.
Lists all org memberships for a user (admin only). Response:

View own organisation

Available to any authenticated user. Returns the caller’s current organisation, including members of that org only. Response:
Returns 404 Not Found if the user has no organisation assigned yet.

Relationship to API keys

Every API key has an organisation_id. When a moderator or admin creates a key:
  1. The server validates that the supplied organisation_id matches the requesting user’s own organisation — cross-org key creation is rejected with 400 Bad Request.
  2. The key appears in GET /api/api-keys/org/{organisation_id} for all moderators/admins in that org.
See Authentication — User API keys for key creation details and workspace scoping.

Relationship to prompt overrides

Overrides are stored in customer_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.

Admin UI

Organisation management is available under Admin → Users → Edit User. The “Organisation” dropdown lists all organisations and includes an inline “Add new organisation” option that creates the org and selects it without leaving the modal.