Administration — API reference

Tenancy, members & auth, personas, settings & LLM connections, retention, and the audit log.

auth

POST /auth/accept-invite

Accept Invite

Activate an invited user: set their password from a one-time token, log them in.

POST /auth/change-password

Change Password

Change the signed-in user’s password after re-verifying the current one.

PUT /auth/digest

Set Digest

Set the signed-in user’s persona digest email preference.

POST /auth/digest/test

Send Test Digest

Compose the signed-in user’s persona digest NOW and send it, ignoring the daily cadence.

POST /auth/forgot-password

Forgot Password

Begin a forgotten-password reset for a registered user. Always returns a uniform 200.

PUT /auth/locale

Set Locale

Persist the signed-in user’s preferred UI language.

POST /auth/login

Login

Verify email + password, issue a session token, return it with the user profile.

POST /auth/logout

Logout

Revoke the presented session token (best-effort; idempotent).

GET /auth/me

Me

Return the currently authenticated user, or 401 if there is no valid session.

GET /auth/mfa

Mfa Status

The caller’s own MFA state. Reachable on an mfa_pending session — it is what the enrolment screen reads to know what to show.

POST /auth/mfa/challenge

Mfa Challenge

Exchange a nk_mfa_… token + a second factor for a real session. Unauthenticated.

POST /auth/mfa/disable

Mfa Disable

Turn the second factor off, after re-proving BOTH the password and the factor itself.

POST /auth/mfa/enroll

Mfa Enroll

Issue a fresh TOTP secret + provisioning URI. Does not enable anything.

POST /auth/mfa/recovery-codes

Mfa Regenerate Recovery Codes

Replace every outstanding recovery code. Returns the new set, shown once.

POST /auth/mfa/verify

Mfa Verify

Confirm a code against the PENDING secret, then enable MFA and mint the recovery codes.

GET /auth/password-policy

Password Policy

The set-password rules the server will actually enforce: {minLength, breachCheck}.

PUT /auth/persona

Set Persona

Record the signed-in user’s persona lens.

POST /auth/reset-password

Reset Password

Complete a forgotten-password reset from a one-time token, then sign the user in.

GET /auth/reset-password/validate

Validate Reset Token

Cheap pre-flight check the reset page runs before showing its form.

GET /auth/sessions

List Sessions

The caller’s OWN live sessions — “where am I signed in”.

POST /auth/sessions/revoke-all

Revoke All Sessions

Sign out everywhere. Returns {"revoked": n} — how many sessions were actually ended.

DELETE /auth/sessions/{session_id}

Revoke Session

Revoke ONE of the caller’s own sessions — the “I don’t recognise that device” action.

GET /auth/sso/connections

List Connections

List this company’s SSO connections (client secrets never returned).

POST /auth/sso/connections

Create Connection

Create an SSO connection for this company. Protocol-specific required fields are validated before the store persists (and Fernet-encrypts any client secret).

GET /auth/sso/connections/{connection_id}

Get Connection

Read one connection (company-scoped; client secret never returned).

PATCH /auth/sso/connections/{connection_id}

Update Connection

Patch a connection (company-scoped). A raw oidcClientSecret is encrypted by the store; a supplied required field may not be blanked.

DELETE /auth/sso/connections/{connection_id}

Delete Connection

Delete a connection and its domain mappings (company-scoped).

PUT /auth/sso/connections/{connection_id}/domains

Set Connection Domains

Set the email domains routed to this connection (home-realm discovery). A domain already claimed by another company hits the UNIQUE index — surfaced as a clean 409.

GET /auth/sso/oidc/callback

Sso Oidc Callback

OIDC authorization-code callback: consume state, exchange the code with PKCE, fully validate the id_token, JIT-provision, and deliver the session (or an MFA challenge) to the SPA.

GET /auth/sso/providers

Sso Providers

Which SSO connection (if any) serves this email’s domain — the login page’s “Sign in with SSO” affordance. No secrets in the response.

POST /auth/sso/saml/acs

Sso Saml Acs

SAML Assertion Consumer Service (SP-initiated POST binding): validate the signed assertion and deliver the session (or an MFA challenge) to the SPA.

GET /auth/sso/saml/{connection_id}/metadata

Sso Saml Metadata

SP metadata XML for the IdP administrator (application/xml).

GET /auth/sso/{connection_id}/start

Sso Start

Begin an SSO login: build the authz redirect and 302 to the IdP.

GET /me/workspace

Workspace

Single bootstrap contract the SPA renders its shell from.

tenancy

GET /companies

List Companies

GET /memberships

List Memberships

GET /orgs

List Orgs

POST /orgs

Create Org

Create an org in the caller’s company (admin-gated; enforces the tier’s org cap).

PATCH /orgs/{org_id}

Update Org

Rename an org (or update its slug) within the caller’s company.

GET /overview

Overview

Tenancy tree (companies → orgs → projects) with per-project session counts.

GET /projects

List Projects

POST /projects

Create Project

Create a new project under an org.

GET /projects/current

Current Project

Report the project THIS connection is scoped to.

GET /projects/{project_id}

Get Project

PATCH /projects/{project_id}

Update Project

DELETE /projects/{project_id}

Delete Project

Delete a project and every data-plane row scoped to it.

PUT /projects/{project_id}/prefs

Set Project Pref

Toggle the current user’s per-user preference for a project (favorite on/off).

GET /users

List Users

members

GET /members

List Members

List the caller company’s members (directory users + their status/role).

POST /members/bulk-orgs

Bulk Set Orgs

Assign org access to several members at once.

POST /members/bulk-persona

Bulk Assign Persona

Set (or clear) the persona DEFAULT for a set of the caller company’s members at once.

POST /members/invite

Invite Member

Invite a new member: create an invited directory user + a one-time activation link.

PATCH /members/{user_id}

Update Member

Change a member’s role or status (e.g. disable). Scoped to the caller’s company.

DELETE /members/{user_id}

Remove Member

Remove a member (delete the directory user + revoke their sessions).

GET /members/{user_id}/activity

Member Activity

Lifecycle timeline for one member: the tenant audit events targeting them.

PUT /members/{user_id}/orgs

Set Member Orgs

Assign a member to one or more orgs. A full REPLACE of the member’s org-scoped membership grants, scoped to the caller’s company. Admin-gated.

POST /members/{user_id}/resend-invite

Resend Invite

Rotate an invited member’s activation token and return a fresh one-time link.

personas

GET /personas

Get Personas

List the personas (lenses) available to the caller’s tenant — powers the switcher/modal.

POST /personas

Create Persona Route

Create a tenant-authored (custom) persona lens. Admin + custom_personas (Silver+).

PATCH /personas/{key}

Update Persona Route

Edit a persona. Editing a platform lens flips it to custom provenance (freezing it — it stops receiving code upgrades); an already-custom lens is edited in place. The always-on full_workspace escape hatch can’t be customized.

DELETE /personas/{key}

Delete Persona Route

Delete a custom persona. Deleting a customized platform key resets it to the shipped default (re-seeded on the next ensure); deleting a purely-custom key also clears it from any member who had it as a default (they fall back to their role-derived lens). Platform lenses that were never customized, and full_workspace, can’t be deleted.

settings

GET /llm-connections

List Llm Connections

POST /llm-connections

Create Llm Connection

POST /llm-connections/list-models

List Llm Connection Models

List the model ids a connection’s provider advertises, for the model picker.

POST /llm-connections/probe

Probe Llm Connection

Live connection probe: makes a real completion through the provider and returns reachability. Used by the UI ‘Test’ action. Never persists anything. A completion that only ran out of token budget (finish_reason=length) still counts as reachable.

PATCH /llm-connections/{conn_id}

Update Llm Connection

DELETE /llm-connections/{conn_id}

Delete Llm Connection

GET /settings

Get Settings

GET /settings/api-keys

List Api Keys

POST /settings/api-keys

Create Api Key

POST /settings/api-keys/revoke

Revoke Api Key

preferences

GET /preferences/table-columns

Get Table Columns

PUT /preferences/table-columns

Put Table Columns

onboarding

POST /onboarding/complete

Complete Onboarding

POST /onboarding/dismiss

Dismiss Onboarding

POST /onboarding/provision

Provision Onboarding

GET /onboarding/status

Get Onboarding Status

GET /onboarding/tenant

Get Tenant Onboarding

POST /onboarding/tenant/ack

Ack Tenant Step

Mark a checklist step acknowledged by the admin (idempotent).

POST /onboarding/tenant/complete

Complete Tenant Onboarding

POST /onboarding/tenant/dismiss

Dismiss Tenant Onboarding

retention

GET /retention/erasure

List Erasures

List erasure requests for the tenant, newest first (compliance evidence register).

POST /retention/erasure

Create Erasure

Submit a GDPR Art. 17 erasure. Validates the selector is non-empty (an empty selector can never fan out to “erase everything”), records a pending request, and starts the erasure asynchronously — poll the request for its terminal status and manifest.

GET /retention/erasure/{request_id}

Get Erasure

GET /retention/policies

List Policies

List the tenant’s retention policies + a preview of the effective retention (days) resolved per project (most-specific-first: project override → company policy → platform env default).

PUT /retention/policies

Upsert Policy

Create or update a retention policy for a scope. A company policy is forced to the caller’s own company (its scope_id can’t be spoofed); a project policy requires an explicit scope_id (the project). retention_days is clamped to >= 0 (0 = keep forever). Upserts on the unique (scope_type, scope_id) pair.

DELETE /retention/policies/{policy_id}

Delete Policy

Delete a retention policy (the scope reverts to the next-coarser effective window).

audit

GET /audit

List Audit

Admin-only tenant audit log. Filterable by action/actor/target/org/project/status, the canonical time ticker, and a free-text q (substring over summary/target name/ action). Returns {data, meta:{total, limit, offset, facets}}.

GET /audit/trend

Audit Trend

Event-volume trend for the admin audit log: per-day (or per-hour) count of audit events over the selected window. Scoped to the events you can see — your company’s, plus shared-schema events — never another company’s.