Tenants API
Reference for the Tenants endpoint group — 5 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/tenants/#
List Tenants
List all tenants.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
page |
query | no | integer |
|
per_page |
query | no | integer |
|
search |
query | no | string | null |
|
status |
query | no | string | null |
|
partner_id |
query | no | string | null |
|
authorization |
header | no | string | null |
|
x-api-key |
header | no | string | null |
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
POST /api/v1/admin/tenants/#
Create Tenant
Create a new tenant.
Authorization: super_admin may create under any partner. A partner_admin
may create tenants under its own partner only when that partner has
tenant self-management enabled (settings.allow_tenant_self_management), up
to the partner's max_tenants quota; partner_id is pinned server-side.
Without the flag → 403; over quota → 409.
Request body (application/json):
| Field | Type | Required | Notes |
|---|---|---|---|
name |
string | yes | Display name. |
slug |
string | yes | URL-safe, unique. |
contact_email |
string | no | Primary contact. |
partner_id |
string | yes for super_admin |
Owning partner. Ignored for a partner_admin (pinned to its own). |
status |
string | no | Default active. |
settings |
object | no | Tenant settings; inherits partner defaults if omitted. |
branding |
object | no | Tenant branding. |
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
authorization |
header | no | string | null |
|
x-api-key |
header | no | string | null |
Request body:
Required.
application/json→ object
Responses:
| Status | Body |
|---|---|
201 |
application/json → any |
422 |
application/json → HTTPValidationError |
DELETE /api/v1/admin/tenants/{tenant_id}#
Delete Tenant
Soft delete a tenant.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | yes | string |
|
authorization |
header | no | string | null |
|
x-api-key |
header | no | string | null |
Responses:
| Status | Body |
|---|---|
204 |
Successful Response |
422 |
application/json → HTTPValidationError |
GET /api/v1/admin/tenants/{tenant_id}#
Get Tenant
Get a tenant by ID.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | yes | string |
|
authorization |
header | no | string | null |
|
x-api-key |
header | no | string | null |
Responses:
| Status | Body |
|---|---|
200 |
application/json → any |
422 |
application/json → HTTPValidationError |
PATCH /api/v1/admin/tenants/{tenant_id}#
Update Tenant
Update a tenant.
Settings can include:
- mfa_required: bool - Whether MFA is required for all users
- mfa_methods: list - Allowed MFA methods ['totp', 'sms', 'email', 'webauthn']
- password_policy: object - Password requirements (see below)
- session_timeout: int - Session timeout in minutes
password_policy object:
| Field | Type | Default | Notes |
|---|---|---|---|
min_length |
integer | 8 |
6-128. |
require_uppercase |
boolean | false |
Require at least one A-Z. |
require_lowercase |
boolean | false |
Require at least one a-z. |
require_numbers |
boolean | false |
Require at least one digit. |
require_special |
boolean | false |
Require at least one non-alphanumeric. |
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | yes | string |
|
authorization |
header | no | string | null |
|
x-api-key |
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 |