Organizations API — User Service

User Service endpoints for organizations, organization membership, roles, and permissions. For architecture and configuration, see User Service. Project-level membership and roles are covered in Projects API.

All endpoints require Authorization: Bearer YOUR_TOKEN. Non-superusers must also send X-Org-Id, and their requests are scoped to that organization. Lists use page-number pagination (page, page_size; default 10, max 100) unless noted. See API Conventions.

Endpoint Summary

Organizations

Organization object

Detail responses also include user_mappings.

List organizations

GET /api/v1/organizations/?search=acme&is_active=true

Filters: name, is_active. Search (search) matches name and description. Superusers see all organizations; other users see only the organization in X-Org-Id.

Create organization

POST /api/v1/organizations/

{"name": "Acme", "description": "Acme Corp tenant", "mfa_required": false}

Returns 201 with the organization object. The creator is added with the Guest organization role. No project is created automatically; create projects through the Projects API.

Update organization

PATCH /api/v1/organizations/{id}/

Send JSON for field changes, or multipart/form-data to upload logo_file. Setting mfa_required without org_manage_security returns 403.

Activate or deactivate

POST /api/v1/organizations/{id}/activate/
POST /api/v1/organizations/{id}/deactivate/

Response 200: {"message": "Organization activated successfully"} (or deactivated).

Organization metrics

GET /api/v1/organizations/metrics/
X-Org-Id: YOUR_ORG_ID

{"total_members": 42, "total_roles": 6, "total_projects": 5}

X-Org-Id is required. The counts are always organization-wide; X-Project-Id has no effect.

Membership

List members

GET /api/v1/organizations/{id}/users/?search=jane&role=3

Returns a paginated list of user-organization-role mappings (one row per role assignment).

Set a user's roles

POST, PUT, and PATCH on user-organization-roles/ all take the same body and set the complete role list for one user in one organization:

PUT /api/v1/organizations/user-organization-roles/

{"user": "USER_UUID", "organization": "YOUR_ORG_ID", "roles": [3, 5]}

POST returns 201; PUT and PATCH return 200. GET on the same path returns a paginated list grouped by user. DELETE /api/v1/organizations/user-organization-roles/{mapping_id}/ removes a single role assignment; removing the last one removes the user from the organization.

Default organization roles

Each organization has four default roles: Admin, Contributor, Reader, and Guest. Default roles cannot be edited. Organizations can add custom roles through the roles API.

Roles

Roles live under the Access API.

GET /api/v1/access/roles/?organization=YOUR_ORG_ID&expand=permissions

Create a custom role with POST /api/v1/access/roles/ and {"name", "description", "organization", "permissions": [ids]}. Role objects include is_default.

Replace role permissions

PUT /api/v1/access/roles/{id}/permissions/

{"permissions": [12, 15, 31]}

The list replaces the role's permissions. The response is the role (add ?expand=permissions to embed them) plus a change_summary with added, removed, and final. Default roles return 400.

Permissions

GET /api/v1/access/permissions/?search=org_&mode=all

Returns the permission catalog (id, name, code, description). Filter with name or code; search matches name, code, and description; mode=all returns the full list without pagination. Only superusers can create or change permissions.

Permissions are defined in permissions_config.yaml (188 codes). Organization-level codes include:

Other codes cover platform resources such as agents, tools, apps, knowledge bases, observability, and projects. Use the catalog endpoint for the current list.

Errors