Admin Roles API
Reference for the Admin Roles endpoint group — 6 endpoints.
Generated from the live OpenAPI spec. Re-run _generate_api_reference.py after backend changes.
Authentication#
All endpoints require a Bearer JWT in the Authorization header unless noted otherwise. See Concepts → Tokens and scopes and Reference → OAuth endpoints for how to obtain one.
Endpoints#
GET /api/v1/admin/admin-roles/#
List Admin Roles
List all admin role assignments.
Only accessible by Super Admins.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
page |
query | no | integer |
|
per_page |
query | no | integer |
|
role |
query | no | string | null |
Filter by role type |
user_id |
query | no | string | null |
Filter by user |
is_active |
query | no | boolean | null |
Filter by active status |
authorization |
header | no | string | null |
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
POST /api/v1/admin/admin-roles/#
Create Admin Role
Assign an admin role to a user.
Only accessible by Super Admins.
Required fields:
- user_id: The user to assign the role to
- role: SUPER_ADMIN, PARTNER_ADMIN, or TENANT_ADMIN
Conditional fields:
- partner_id: Required for PARTNER_ADMIN
- tenant_id: Required for TENANT_ADMIN
Optional fields:
- expires_at: When the role expires (ISO format)
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
authorization |
header | no | string | null |
Request body:
Required.
application/json→ object
Responses:
| Status | Body |
|---|---|
201 |
application/json → any |
422 |
application/json → HTTPValidationError |
GET /api/v1/admin/admin-roles/user/{user_id}#
Get User Admin Roles
Get all admin roles for a specific user.
Only accessible by Super Admins.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
user_id |
path | yes | string |
|
authorization |
header | no | string | null |
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
DELETE /api/v1/admin/admin-roles/{role_id}#
Delete Admin Role
Revoke an admin role assignment.
Only accessible by Super Admins. Cannot delete your own Super Admin role.
If cleanup_orphaned_user is True (default), will also soft-delete the user if:
- They have no remaining admin roles after this deletion
- They exist in multiple tenants with the same email (duplicate admin user)
- They have never logged in
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
role_id |
path | yes | string |
|
cleanup_orphaned_user |
query | no | boolean |
If true, delete the user if they have no remaining admin roles and appear to be admin-only |
authorization |
header | no | string | null |
Responses:
| Status | Body |
|---|---|
204 |
Successful Response |
422 |
application/json → HTTPValidationError |
GET /api/v1/admin/admin-roles/{role_id}#
Get Admin Role
Get a specific admin role assignment.
Only accessible by Super Admins.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
role_id |
path | yes | string |
|
authorization |
header | no | string | null |
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
PATCH /api/v1/admin/admin-roles/{role_id}#
Update Admin Role
Update an admin role assignment.
Only accessible by Super Admins.
Updatable fields:
- is_active: Activate or deactivate the role
- expires_at: Set or update expiration
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
role_id |
path | yes | string |
|
authorization |
header | no | string | null |
Request body:
Required.
application/json→ object
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
Schemas#
Definitions for every type referenced by the endpoints above. Schema-to-schema references on this page link within the page; cross-page references would require visiting the linked page.
HTTPValidationError#
| Field | Type | Required | Description |
|---|---|---|---|
detail |
array of ValidationError |
no |
ValidationError#
| Field | Type | Required | Description |
|---|---|---|---|
loc |
array of string | integer |
yes | |
msg |
string |
yes | |
type |
string |
yes |