Organizations API

The Organizations API manages organizations, their members, and email invitations. All endpoints require an authenticated session (cookie or Authorization: Bearer …) and are scoped to the current Application via X-App-Id / host context.

Authorization model

Mutations are gated by permissions, not role strings. Every organization-scoped route resolves the caller's role through organization_members and walks the per-app catalog (see Organization Roles) to derive the permission set.

The four permissions used by the API are:

Default role → permission mapping:

Response codes for authorization

The 404-for-non-members rule is intentional and prevents cross-tenant probing for organization IDs.

Organizations

Slugs are unique per application, 3–63 chars, ^[a-z](?:[a-z0-9-]*[a-z0-9])?$, no consecutive hyphens.

GET /api/organizations/:id returns the caller's role and the permission set their role grants, so the dashboard can render permission-gated UI without an extra round-trip:

{
  "organization": { "id": "…", "name": "…", "slug": "…", … },
  "caller": {
    "user_id": "…",
    "role": "admin",
    "permissions": ["org:read", "org:manage", "org:members:write", "org:invitations:write"]
  },
  "member_count": 7
}

Members

Role-change and remove endpoints return 409 when the action would leave the organization with zero members holding org:manage. The guard lives in the SQL WHERE clause, so two concurrent self-demotes cannot both succeed. See Organization Roles → Last-org:manage guard.

Custom roles

Custom roles are managed through /api/organizations/:id/roles. The :id segment is a permission-gating context (the caller must hold org:manage in that org), but the role definitions themselves are app-scoped — once created, a role is available in every organization of the application.

GET /api/organizations/:id/roles returns both the role list (presets + custom) and the permission catalog:

{
  "roles": [
    {
      "id": "orgrole:app_abc:admin",
      "name": "admin",
      "description": "…",
      "is_system": true,
      "permissions": ["org:read", "org:manage", "org:members:write", "org:invitations:write"]
    },
    {
      "id": "<uuid>",
      "name": "billing",
      "description": "Read-only finance",
      "is_system": false,
      "permissions": ["org:read"]
    }
  ],
  "permissions": [
    { "id": "orgperm:app_abc:org:read", "name": "org:read", "description": "View the organization, its members, and pending invitations" }
  ]
}

POST body — { name, description?, permissions: string[] }. Returns 201. Errors: 400 (unknown permission name), 403 (caller missing org:manage), 409 (name in use, including admin / member).

PUT body — { name?, description?, permissions? }, at least one field required. Setting permissions replaces the set wholesale. Errors: 400 (unknown permission), 403 (preset / is_system = 1), 404 (not found), 409 (name collision).

DELETE — 403 for presets, 404 for not-found, 409 when one or more members still hold the role (body includes in_use_count).

Audit events: org_role_created, org_role_updated, org_role_deleted.

Invitations

The list endpoint is visible to any member (org

Invitation tokens are 64 hex characters. The accept endpoint requires the caller's email to match the invitation's email (case-insensitive). Email link target: {appPublicBaseUrl}/accept-org-invite?token=....

Audit events

Active organization

Returns 404 to non-members and for organizations in other applications (deliberate — avoids cross-tenant probing). The active_org_id claim is a hint surfaced through GET /api/users/me; per-request authorization always re-checks organization_members, so a forged or stale claim never grants access.

/api/users/me echo

GET /api/users/me re-validates the JWT's active_org_id claim against organization_members on every call. The response always includes the active-org trio plus an org_count field (used by the org switcher); if the user is still a member, the trio is populated:

{
  "active_org_id": "org_abc…",
  "active_org_role": "admin",
  "active_org_permissions": ["org:read", "org:manage", …],
  "org_count": 3
}

If membership has been revoked, the three active_org_* fields are null in the response (the claim is silently dropped — the JWT itself is not rewritten). org_count is unaffected. This lets the dashboard treat the trio as a source of truth without re-fetching the org just to know whether the claim is still valid.

Related

• Organizations — Overview and concepts
• Membership & Invitations — Membership and invitation flows
• Organization Roles — Permission catalog, role presets, and the last-org:manage guard