This endpoint requires admin-level roles. The Go API Gateway enforces RequireAnyRole("tenant_admin", "platform_admin", "system_admin", "super_admin") on all /v1/tenants/* routes. Lifecycle operations (suspend, resume, activate, deactivate) additionally require platform_admin, platform_operator, system_admin, or super_admin.
Tenants API
Manage organizations, hierarchies, configuration, feature flags, roles, and role assignments.
Overview
The Tenants API provides organization management through the Go API Gateway at /v1/tenants/*. All requests are proxied to the Rust Platform service.
| Feature | Description |
|---|---|
| Tenant CRUD | Create, list, get, and update tenants |
| Lifecycle | Suspend, resume, activate, deactivate tenants |
| Hierarchy | Get children and full hierarchy trees |
| Configuration | Read and update tenant configuration |
| Categories | List and create tenant categories |
| Feature Flags | List, create, and delete per-tenant feature flags |
| Roles | CRUD for tenant-scoped roles |
| Role Assignments | Assign and revoke role assignments |
List Tenants
Request
GET /v1/tenants
Authorization: Bearer {access_token}
Query Parameters
| Parameter | Type | Description |
|---|---|---|
parent_id | string (UUID) | Filter by parent tenant ID |
tenant_level | integer | Filter by hierarchy level (positive integer) |
include_children | boolean | Include children in response (true or false) |
page | integer | Page number (positive integer) |
limit | integer | Results per page (positive integer) |
Create Tenant
Request
POST /v1/tenants
Authorization: Bearer {access_token}
Content-Type: application/json
The request body is forwarded to the Rust Platform service at POST /api/v1/tenants.
Get Tenant
Request
GET /v1/tenants/{tenant_id}
Authorization: Bearer {access_token}
| Parameter | Type | Description |
|---|---|---|
tenant_id | path (UUID) | Tenant identifier |
Update Tenant
Request
PATCH /v1/tenants/{tenant_id}
Authorization: Bearer {access_token}
Content-Type: application/json
| Parameter | Type | Description |
|---|---|---|
tenant_id | path (UUID) | Tenant identifier |
The request body is forwarded to the Rust Platform service at PATCH /api/v1/tenants/{tenant_id}.
Tenant Lifecycle Operations
These endpoints manage tenant state transitions. They all require an elevated role: platform_admin, platform_operator, system_admin, or super_admin.
Suspend Tenant
POST /v1/tenants/{tenant_id}/suspend
Authorization: Bearer {access_token}
Content-Type: application/json
Request body is optional.
Resume Tenant
POST /v1/tenants/{tenant_id}/resume
Authorization: Bearer {access_token}
Content-Type: application/json
Request body is optional.
Activate Tenant
POST /v1/tenants/{tenant_id}/activate
Authorization: Bearer {access_token}
Content-Type: application/json
Request body is optional.
Deactivate Tenant
POST /v1/tenants/{tenant_id}/deactivate
Authorization: Bearer {access_token}
Content-Type: application/json
Request body is optional.
Tenant Hierarchy
Get Children
Returns direct child tenants.
GET /v1/tenants/{tenant_id}/children
Authorization: Bearer {access_token}
| Parameter | Type | Description |
|---|---|---|
tenant_id | path (UUID) | Parent tenant identifier |
page | query (integer) | Page number |
limit | query (integer) | Results per page |
Get Hierarchy
Returns the full hierarchy tree for a tenant.
GET /v1/tenants/{tenant_id}/hierarchy
Authorization: Bearer {access_token}
| Parameter | Type | Description |
|---|---|---|
tenant_id | path (UUID) | Tenant identifier |
Tenant Configuration
Get Configuration
GET /v1/tenants/{tenant_id}/configuration
Authorization: Bearer {access_token}
Update Configuration
PATCH /v1/tenants/{tenant_id}/configuration
Authorization: Bearer {access_token}
Content-Type: application/json
The request body is forwarded to the Rust Platform service.
Tenant Categories
List Categories
GET /v1/tenants/{tenant_id}/categories
Authorization: Bearer {access_token}
Create Category
POST /v1/tenants/{tenant_id}/categories
Authorization: Bearer {access_token}
Content-Type: application/json
Tenant Feature Flags
List Feature Flags
GET /v1/tenants/{tenant_id}/feature-flags
Authorization: Bearer {access_token}
Create Feature Flag
POST /v1/tenants/{tenant_id}/feature-flags
Authorization: Bearer {access_token}
Content-Type: application/json
Delete Feature Flag
DELETE /v1/tenants/{tenant_id}/feature-flags/{flag_key}
Authorization: Bearer {access_token}
| Parameter | Type | Description |
|---|---|---|
tenant_id | path (UUID) | Tenant identifier |
flag_key | path (string) | Feature flag key |
Tenant Roles
List Roles
GET /v1/tenants/{tenant_id}/roles
Authorization: Bearer {access_token}
Create Role
POST /v1/tenants/{tenant_id}/roles
Authorization: Bearer {access_token}
Content-Type: application/json
Update Role
PUT /v1/tenants/{tenant_id}/roles/{role_id}
Authorization: Bearer {access_token}
Content-Type: application/json
| Parameter | Type | Description |
|---|---|---|
tenant_id | path (UUID) | Tenant identifier |
role_id | path (UUID) | Role identifier |
Delete Role
DELETE /v1/tenants/{tenant_id}/roles/{role_id}
Authorization: Bearer {access_token}
Tenant Role Assignments
List Role Assignments
GET /v1/tenants/{tenant_id}/role-assignments
Authorization: Bearer {access_token}
Create Role Assignment
POST /v1/tenants/{tenant_id}/role-assignments
Authorization: Bearer {access_token}
Content-Type: application/json
Revoke Role Assignment
POST /v1/tenants/{tenant_id}/role-assignments/{assignment_id}/revoke
Authorization: Bearer {access_token}
Content-Type: application/json
| Parameter | Type | Description |
|---|---|---|
tenant_id | path (UUID) | Tenant identifier |
assignment_id | path (UUID) | Assignment identifier |
Error Responses
Validation Error (400)
Returned when path parameters fail UUID validation or query parameters are invalid.
{
"error": "validation_error",
"message": "tenant_id must be a valid UUID"
}
Permission Denied (403)
Returned when the caller lacks required roles for lifecycle operations.
{
"error": "permission_denied",
"message": "platform admin role required"
}
Upstream Error (502)
Returned when the Rust Platform service is unavailable or returns an error.
Related Documentation
- Locations API - Location management
- Users API - User management
- Roles API - Role management
- Gating API - Feature gating