Tenant API
The Tenant API provides REST endpoints for managing tenants, their organizational hierarchy (departments), roles, groups, applications, property templates, and user assignments. Access requires a Keycloak admin bearer token with appropriate realm-management permissions.
Scope
The API covers the following domain areas:
- Tenant lifecycle — create, read, update, delete, and search tenants
- Departments — hierarchical organizational units within a tenant, including tree views and sub-departments
- Department users — assign and unassign users to departments
- Roles — manage realm and client roles scoped to a tenant
- Groups — associate Keycloak groups with a tenant
- Property templates — define typed property schemas for structured department metadata
- Department templates — reusable department blueprints organized into template groups
- Applications — global application catalog and tenant-scoped application assignments
- User assignments — query user-to-tenant assignment data across departments
Definitions
Tenant lifecycle
| Operation | Description |
|---|---|
| List tenants | Retrieve tenants with pagination and search filtering |
| Get tenant | Retrieve a single tenant by ID |
| Create tenant | Provision a new tenant with name, alias, description, and domain associations |
| Update tenant | Modify tenant metadata or toggle enabled status |
| Delete tenant | Permanently remove a tenant and all associated resources |
| Search by alias | Look up a tenant by its unique alias |
Departments
| Operation | Description |
|---|---|
| List root departments | Retrieve top-level departments within a tenant |
| Get department tree | Retrieve the full hierarchical tree as nested nodes |
| Create department | Add a department with optional template, roles, and attributes |
| Get department | Retrieve a single department with template-inherited data |
| Update department | Modify department metadata, roles, or attributes |
| Delete department | Remove a department |
| List / create / get / update / delete sub-departments | Manage departments nested under a parent department |
Department users
| Operation | Description |
|---|---|
| List department users | Retrieve users assigned to a department with their roles |
| Assign user | Assign a user to a department with optional roles and attributes |
| Unassign user | Remove a user from a department |
Roles
| Operation | Description |
|---|---|
| List organization roles | Retrieve roles assigned to a tenant, with optional global filter |
| List available roles | Retrieve roles not yet assigned to a tenant |
| Add role | Assign an existing realm or client role to a tenant |
| Remove role | Unassign a role from a tenant |
| Create and assign role | Create a new realm role and assign it to a tenant in one operation |
| List global realm roles | Retrieve all realm-level roles |
| List department roles | Retrieve realm or client roles scoped to a department |
Groups
| Operation | Description |
|---|---|
| List organization groups | Retrieve Keycloak groups associated with a tenant |
| Add group | Associate a Keycloak group with a tenant |
| Remove group | Disassociate a group from a tenant |
Property templates
| Operation | Description |
|---|---|
| List / get / create / update / delete property templates | Manage typed property schemas (STRING, NUMERIC, DATE, BOOLEAN) for department metadata |
Department templates
| Operation | Description |
|---|---|
| List / get / create / update / delete department templates | Manage reusable department blueprints with predefined roles and attributes |
| List / add / remove template roles | Manage roles assigned to a department template |
| List / get / create / update / delete template groups | Organize department templates into logical collections |
| Clone template group | Duplicate a template group and all its templates |
Applications
| Operation | Description |
|---|---|
| List / get / create / update / delete global applications | Manage the realm-level application catalog |
| List tenant applications | Retrieve applications assigned to a tenant |
| Assign application to tenant | Associate a global application with a tenant |
| Unassign application from tenant | Remove an application assignment without deleting the application |
User assignments
| Operation | Description |
|---|---|
| List user assignments | Retrieve all department assignments for a user |
| Get user assignment tree | Retrieve the organization hierarchy filtered to a user's departments |
Example
{
"method": "POST",
"path": "/tenants",
"body": {
"name": "Acme Corp",
"alias": "acme",
"description": "Primary tenant for Acme Corporation",
"domains": [
{ "name": "acme.example.com" }
]
}
}