API
Tenant: users, groups, roles and policies
Administer an organization's members, invites, groups, roles, sign-in clients, sign-in logs and sign-in policy.
Reads need tenant:read, changes tenant:write (owners and admins, or a custom role with them). Changes that touch owners, and the sign-in policy, need an owner; nobody assigns a role with scopes they don't hold. Every change is recorded in the audit log. See Tenant for what each part does.
Every route below, with its parameters, request and response, errors and samples, is in the API reference.
| Route | What it does |
|---|---|
GET /v1/orgs/:orgId/tenant/access-requests | The organisation's open and recent access requests from its members (tenant:read). |
POST /v1/orgs/:orgId/tenant/access-requests/:requestId | Answers an access request (answer, and groupId when it grants through a group); owners and admins only (tenant:write). The person who asked is told. |
GET /v1/orgs/:orgId/tenant/groups | Groups with their size, owners and the roles they grant. |
POST /v1/orgs/:orgId/tenant/groups | Creates a group; owners default to the person creating it. role is a built-in role members get (not owner). |
GET /v1/orgs/:orgId/tenant/groups/:teamId | Members, owners, granted roles, Serverless App Service and repository access, and app assignments. |
PATCH /v1/orgs/:orgId/tenant/groups/:teamId | Name, description, the built-in role members get (null removes it) and custom roles. |
DELETE /v1/orgs/:orgId/tenant/groups/:teamId | Deletes the group with its memberships, access and assignments (members keep their own roles). |
PUT /v1/orgs/:orgId/tenant/groups/:teamId/members/:userId | Adds a member or changes their group role (owner manages the group's members, member). |
DELETE /v1/orgs/:orgId/tenant/groups/:teamId/members/:userId | Takes a member out of the group. |
PUT /v1/orgs/:orgId/tenant/groups/:teamId/grants/:resourceType/:resourceId | Gives the group write access to one Serverless App Service or repository. |
DELETE /v1/orgs/:orgId/tenant/groups/:teamId/grants/:resourceType/:resourceId | Removes the group's write access to the Serverless App Service or repository. |
GET /v1/orgs/:orgId/tenant/roles | Built-in roles with their scopes, custom roles, and who holds each. |
POST /v1/orgs/:orgId/tenant/roles | Creates a custom role: a named set of scopes added on top of a member's role. |
PATCH /v1/orgs/:orgId/tenant/roles/:roleId | Renames a custom role or changes its scopes (you need every scope it grants, before and after). |
DELETE /v1/orgs/:orgId/tenant/roles/:roleId | Deletes a custom role; members and groups holding it lose its scopes. |
POST /v1/orgs/:orgId/tenant/roles/:roleId/assignments | Assigns a role (a built-in role id such as admin, or a custom rol_…) to a member or group. A built-in role replaces a member's role; a group grants one built-in role at most. |
DELETE /v1/orgs/:orgId/tenant/roles/:roleId/assignments/:principalType/:principalId | Takes a custom role from a member or group, or the built-in role a group grants. |
GET /v1/orgs/:orgId/tenant/apps | The org's sign-in clients (per Serverless App Service) with assignment and secret expiry, MCP clients members connected here, and its keys. |
GET /v1/orgs/:orgId/tenant/apps/:clientId | One sign-in client: redirect URIs, secret expiry and who is assigned. |
PATCH /v1/orgs/:orgId/tenant/apps/:clientId | assignmentRequired: only assigned people and groups can sign in (checked at sign-in and every refresh). |
POST /v1/orgs/:orgId/tenant/apps/:clientId/secret | Replaces the secret (the old one stops at once) with one valid for expiresInDays (0: no expiry); shown once. |
POST /v1/orgs/:orgId/tenant/apps/:clientId/assignments | Lets a member or group sign in to an app that requires assignment. |
DELETE /v1/orgs/:orgId/tenant/apps/:clientId/assignments/:principalType/:principalId | Takes a member's or group's assignment away; their next refresh is refused. |
DELETE /v1/orgs/:orgId/tenant/apps/:clientId/connections | Disconnects an MCP client from this org for every member. |
GET /v1/orgs/:orgId/tenant/app-access | Every app the org can switch, with its access (everyone, groups, off), whether the plan has it and how many reach it; and the groups. |
PUT /v1/orgs/:orgId/tenant/app-access/:key | Sets who reaches an app: { access: "everyone" | "groups" | "off", groupIds? }. Owners and admins, themselves; owners and admins always reach it. |
GET /v1/orgs/:orgId/tenant/app-switcher | Every app the org can hide from the switcher (its apps, never Tenant), in the launcher's order, with whether it does. |
PUT /v1/orgs/:orgId/tenant/app-switcher/:key | Hides an app from everyone's switcher in the org ({ hidden: true }) or shows it again. Owners and admins, themselves; audited org_app.switcher. |
GET /v1/orgs/:orgId/tenant/sign-ins | Members' sign-ins and failed sign-ins, newest first: method, address, approximate place, device. |
GET /v1/orgs/:orgId/tenant/policies/assistant | Caity in this org (docs/specs/onboarding/caity.md): on or off, the highest mode, the apps she may use; and the choices. |
PUT /v1/orgs/:orgId/tenant/policies/assistant | Sets Caity's policy: { enabled, maxMode, apps, publicShares } (apps: null: every app). Narrowing by owners and admins, widening by owners; audited. |
GET /v1/orgs/:orgId/tenant/policies/sharing | The sharing policy (docs/tenant/sharing-policy.md): how much goes outside the organisation, to which domains, links for how long. |
PUT /v1/orgs/:orgId/tenant/policies/sharing | Sets it: { externalSharing: off|accounts|links, allowedDomains?, linkMaxDays? }. Narrowing by owners and admins, widening by owners; audited. A change that stops links anyone could open tells their owners (linksStopped: how many). |
GET /v1/orgs/:orgId/tenant/policies | The sign-in policy and the members it would leave without access. |
PUT /v1/orgs/:orgId/tenant/policies/sign-in | Sets the sign-in policy (owners): required strength (any, mfa: a passkey or text codes, passkey), allowed methods, a grace period in days and the longest a sign-in lasts in hours. |
GET /v1/orgs/:orgId/tenant/keys | Every key of the organization with its creator, scopes, expiry, status and last use (when, address, country, client). Never secrets. |
DELETE /v1/orgs/:orgId/tenant/keys/:keyId | Revokes a key of the organization at once; audited as key.revoke. |
GET /v1/orgs/:orgId/tenant/sso | Single sign-on and SCIM: what to give the identity provider (entity id, ACS, metadata, OpenID Connect redirect and SCIM URLs), the verified domains, the identity provider's settings (SAML certificates' subjects and expiry; the OpenID Connect issuer, client id and secret's last four characters), and the SCIM token's last four characters. |
PUT /v1/orgs/:orgId/tenant/sso | Saves the identity provider and turns it on or off. SAML: entity id, https sign-in URL, one or two signing certificates (left out keeps the saved ones). OpenID Connect (protocol: "oidc"): the issuer (its discovery document is read and must name it), client id and client secret (sealed; left out keeps it for the same client, null for a public client). The other protocol's settings are kept. On needs a verified domain. Owners. |
DELETE /v1/orgs/:orgId/tenant/sso | Removes the identity provider. Owners. |
POST /v1/orgs/:orgId/tenant/sso/scim-token | A new SCIM token (replacing any): shown this once. |
DELETE /v1/orgs/:orgId/tenant/sso/scim-token | Revokes the SCIM token: provisioning stops. Owners. |
GET /v1/orgs/:orgId/tenant/users | Members with sign-in health; pending invites and removed members (restorable for 30 days). |
GET /v1/orgs/:orgId/tenant/users/export | Every member as CSV (email, name, role, attributes, status, groups, sign-in health). |
GET /v1/orgs/:orgId/tenant/users/:userId/permissions | What a member may do here, app by app, and why (their role, groups, custom roles, the plan and app access). |
GET /v1/orgs/:orgId/tenant/check-access | Check access: whether a member (user) or anyone in a group (group) may use an app (app) or holds a scope (scope) here, with every layer that decides it (membership, space, plan, app access, role, custom roles). Reads only. |
GET /v1/orgs/:orgId/tenant/users/:userId | One member: groups, browser sessions, keys they created, app assignments and recent sign-ins. |
PATCH /v1/orgs/:orgId/tenant/users/:userId | Role, title, department, and a guest's access end (epoch seconds, or null). |
POST /v1/orgs/:orgId/tenant/users/:userId/block | Blocks sign-in to this org: no new tokens; current ones stop at the API and MCP within 30 seconds. |
POST /v1/orgs/:orgId/tenant/users/:userId/unblock | Unblocks sign-in; the person signs in again to reach the org. |
POST /v1/orgs/:orgId/tenant/users/:userId/revoke-sessions | Ends the person's sessions for this org (they sign in again) and disconnects their MCP clients here; keys also revokes keys they created here. |
POST /v1/orgs/:orgId/tenant/users/:userId/password-reset | Emails the member a recovery link at their own address (docs/id/recovery.md); the caller never sees it. |
DELETE /v1/orgs/:orgId/tenant/users/:userId | Removes the member; restorable with their role, attributes, groups and app assignments for 30 days. |
POST /v1/orgs/:orgId/tenant/removed/:userId/restore | Restores a removed member. |
DELETE /v1/orgs/:orgId/tenant/removed/:userId | Forgets a removed member now instead of after 30 days. |
POST /v1/orgs/:orgId/tenant/invites | Invites one person by email (replacing a pending invite to the same address); the link is mailed and returned. |
POST /v1/orgs/:orgId/tenant/invites/bulk | Invites up to 200 people: csv (email[,role[,title[,department]]], header optional) or rows; defaults apply to each. Rows that fail are reported and the rest are sent. |
POST /v1/orgs/:orgId/tenant/invites/:inviteId/resend | A new link for a pending invite (the old one stops working), mailed again. |
DELETE /v1/orgs/:orgId/tenant/invites/:inviteId | Revokes a pending invite (the link stops working). |
GET /v1/orgs/:orgId/tenant/join-codes | Join codes that still work (Invite by Link): role, uses, expiry and who made each; never the codes themselves. |
POST /v1/orgs/:orgId/tenant/join-codes | A join code: anyone signed in who has it joins as role (viewer or developer) for days (1, 7 or 30), up to maxUses people (absent or null: anyone with it). The code and its link are in this answer only. |
DELETE /v1/orgs/:orgId/tenant/join-codes/:codeId | Stops a join code at once; the people it joined stay. |
GET /v1/orgs/:orgId/tenant/domains | The organisation's domains (docs/tenant/domains.md): each one's TXT record, where its checks stand and joining by it. |
POST /v1/orgs/:orgId/tenant/domains | Adds a domain to verify (owners themselves): its record to publish, checked at once and then on the schedule. |
POST /v1/orgs/:orgId/tenant/domains/:domain/verify | Verify: a check now; a domain that failed gets another 72 hours. |
PATCH /v1/orgs/:orgId/tenant/domains/:domain | Joining by the domain (owners themselves): off, offered or automatic, as a viewer or developer, as guests or not. |
DELETE /v1/orgs/:orgId/tenant/domains/:domain | Removes a domain (owners themselves): nobody joins by it, and another organisation can verify it. |
GET /v1/orgs/:orgId/tenant | Properties, counts, the sign-in policy and recommendations computed from the org's data. |
PATCH /v1/orgs/:orgId/tenant | Name, logo (https), contact address and the default language for members who haven't chosen one. |
PUT /v1/orgs/:orgId/tenant/slug | A new slug (owners themselves): the old one keeps redirecting and stays the org's (docs/tenant/slug.md). |
GET /v1/orgs/:orgId/tenant/grantables | Serverless App Services and repositories a group can be given write access to. |