Administration - Tenants
Manage tenants and their OIDC provider configurations. Tenants provide logical isolation for users, roles, and resources within the Koldan platform.
Base path: /api/v1/admin/tenants
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/v1/admin/tenants |
List Tenants |
GET |
/api/v1/admin/tenants/{id} |
Get Tenant |
POST |
/api/v1/admin/tenants |
Create Tenant |
PUT |
/api/v1/admin/tenants/{id} |
Update Tenant |
POST |
/api/v1/admin/tenants/{id}/enable |
Enable Tenant |
POST |
/api/v1/admin/tenants/{id}/disable |
Disable Tenant |
GET |
/api/v1/admin/tenants/{id}/oidc-provider |
Get OIDC Provider |
PUT |
/api/v1/admin/tenants/{id}/oidc-provider |
Upsert OIDC Provider |
DELETE |
/api/v1/admin/tenants/{id}/oidc-provider |
Delete OIDC Provider |
POST |
/api/v1/admin/tenants/{id}/oidc-provider/test |
Test OIDC Provider |
List Tenants
GET /api/v1/admin/tenants
Requires Authentication - Scopes: admin:tenants:read
Returns a paginated list of all tenants with their primary metadata and OIDC provider summary.
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
page |
integer |
No | 0 |
Page number (zero-based). |
size |
integer |
No | 20 |
Page size. |
TenantPageResponse
| Field | Type | Nullable | Description |
|---|---|---|---|
tenants |
TenantResponse[] |
No | Array of tenant objects. |
page |
integer |
No | Current page number. |
size |
integer |
No | Number of items in this page. |
total |
long |
No | Total number of tenants. |
Get Tenant
GET /api/v1/admin/tenants/{id}
Requires Authentication - Scopes: admin:tenants:read
Retrieve detailed information for a single tenant, including its feature settings and OIDC configuration.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id |
string (UUID) |
Yes | Unique identifier of the tenant. |
TenantResponse
Returns the tenant metadata and configuration object.
Create Tenant
POST /api/v1/admin/tenants
Requires Authentication - Scopes: admin:tenants:write
Creates a new tenant with specific role settings and feature flags. Optionally configures an OIDC provider during creation.
TenantCreateRequest
| Field | Type | Required | Description |
|---|---|---|---|
name |
string |
Yes | Unique system name for the tenant (e.g., acme-corp). Max 64 chars. |
displayName |
string |
Yes | Human-readable name (e.g., Acme Corporation). Max 64 chars. |
description |
string |
No | Optional description. Max 256 chars. |
firstLoginRoleId |
string (UUID) |
Yes | Role assigned to the first user who logs in (the tenant owner). |
defaultRoleId |
string (UUID) |
Yes | Default role assigned to subsequent users. |
oidcProvider |
OidcProviderCreateRequest |
No | Optional OIDC configuration. |
speechServiceFileInternalPublishEnabled |
boolean |
No | Enable internal file publishing. Default: true. |
speechServiceFileDirectShareEnabled |
boolean |
No | Enable direct file sharing. Default: true. |
speechServiceSessionMaxConcurrent |
integer |
No | Max concurrent streaming sessions. Default: 50. |
speechServiceSessionRecordingEnabled |
boolean |
No | Enable audio recording for streaming. Default: false. |
TenantResponse
Returns the newly created tenant.
Update Tenant
PUT /api/v1/admin/tenants/{id}
Requires Authentication - Scopes: admin:tenants:write
Update metadata and feature settings for an existing tenant.
TenantUpdateRequest
| Field | Type | Required | Description |
|---|---|---|---|
displayName |
string |
Yes | Updated display name. |
description |
string |
No | Updated description. |
speechServiceFileInternalPublishEnabled |
boolean |
No | Enable/disable internal publishing. |
speechServiceFileDirectShareEnabled |
boolean |
No | Enable/disable direct sharing. |
speechServiceSessionMaxConcurrent |
integer |
No | Updated concurrency limit. |
speechServiceSessionRecordingEnabled |
boolean |
No | Enable/disable streaming recording. |
Enable Tenant
POST /api/v1/admin/tenants/{id}/enable
Requires Authentication - Scopes: admin:tenants:write
Re-enables a previously disabled tenant, allowing users to log in and use platform features.
Disable Tenant
POST /api/v1/admin/tenants/{id}/disable
Requires Authentication - Scopes: admin:tenants:write
Disables a tenant. Active sessions may be terminated, and new logins will be rejected for all users in this tenant.
OIDC Provider Management
Get OIDC Provider
GET /api/v1/admin/tenants/{id}/oidc-provider
Requires Authentication - Scopes: admin:tenants:read
Retrieve the current OIDC configuration for a tenant. Note: The clientSecret is never returned in the response for security reasons.
OidcProviderResponse
Upsert OIDC Provider
PUT /api/v1/admin/tenants/{id}/oidc-provider
Requires Authentication - Scopes: admin:tenants:write
Creates or updates the OIDC provider configuration. This allows the tenant to use an external identity provider (like Keycloak, Okta, or Auth0) for user authentication.
OidcProviderCreateRequest
Delete OIDC Provider
DELETE /api/v1/admin/tenants/{id}/oidc-provider
Requires Authentication - Scopes: admin:tenants:write
Deactivates and removes the OIDC configuration for a tenant. Users will no longer be able to log in via external SSO.
Test OIDC Provider
POST /api/v1/admin/tenants/{id}/oidc-provider/test
Requires Authentication - Scopes: admin:tenants:write
Validates the OIDC configuration by attempting a connectivity test using the client_credentials grant flow.
OidcTestResult
| Field | Type | Nullable | Description |
|---|---|---|---|
success |
boolean |
No | Whether the test was successful. |
message |
string |
Yes | Descriptive status message. |
error |
string |
Yes | Detailed error message if the test failed. |
Data Models
TenantResponse
| Field | Type | Nullable | Description |
|---|---|---|---|
id |
string (UUID) |
No | Tenant unique identifier. |
name |
string |
No | Unique tenant slug. |
displayName |
string |
No | Human-readable name. |
description |
string |
Yes | Tenant description. |
enabled |
boolean |
No | Whether the tenant is active. |
firstLoginRole |
RoleRef |
No | Defines the max privilege ceiling for the tenant owner. |
defaultRole |
RoleRef |
No | Role assigned to new users by default. |
createdAt |
string (ISO 8601) |
No | Creation timestamp. |
oidcProvider |
OidcProviderResponse |
Yes | Active OIDC configuration. |
speechServiceFileInternalPublishEnabled |
boolean |
No | Internal sharing enabled. |
speechServiceFileDirectShareEnabled |
boolean |
No | Direct sharing enabled. |
speechServiceSessionMaxConcurrent |
integer |
No | Max streaming concurrency limit. |
speechServiceSessionRecordingEnabled |
boolean |
No | Streaming recording enabled. |
OidcProviderResponse
| Field | Type | Nullable | Description |
|---|---|---|---|
id |
string (UUID) |
No | Provider record ID. |
providerKey |
string |
No | Provider identifier (e.g., oidc). |
clientId |
string |
No | OAuth2 client ID. |
clientSecretConfigured |
boolean |
No | Whether a secret is stored in the system. |
issuerUri |
string |
No | OIDC issuer URI. |
authorizationUri |
string |
Yes | Authorization endpoint. |
tokenUri |
string |
No | Token endpoint. |
userInfoUri |
string |
Yes | UserInfo endpoint. |
jwkSetUri |
string |
No | JWK Set URI. |
endSessionUri |
string |
Yes | Logout endpoint. |
introspectionUri |
string |
Yes | Token introspection endpoint. |
advertisedIssuer |
string |
Yes | Optional public-facing issuer URL. |
OidcProviderCreateRequest
| Field | Type | Required | Description |
|---|---|---|---|
providerKey |
string |
No | Identifier (defaults to oidc). |
clientId |
string |
Yes | OAuth2 client ID. |
clientSecret |
string |
No | Client secret (plaintext). |
issuerUri |
string |
Yes | OIDC issuer URI. |
authorizationUri |
string |
No | Authorization endpoint. |
tokenUri |
string |
Yes | Token endpoint. |
userInfoUri |
string |
No | UserInfo endpoint. |
jwkSetUri |
string |
Yes | JWK Set URI. |
endSessionUri |
string |
No | Logout endpoint. |
introspectionUri |
string |
No | Token introspection endpoint. |
advertisedIssuer |
string |
No | Optional public issuer URL. |
RoleRef
| Field | Type | Nullable | Description |
|---|---|---|---|
id |
string (UUID) |
No | Role identifier. |
slug |
string |
No | Role slug (e.g., manager). |
name |
string |
No | Role display name. |
hierarchyOrder |
integer |
No | Role privilege level. |