Tenant Management Endpoints

These endpoints can be used to retrieve information from the identity provider. Role and user management for a tenant and to create and delete tenants in Keycloak.

This API is provided by the TENANT-MANAGEMENT Service and expects the corresponding requirements.

A Swagger-UI is available to call the API endpoints manually for testing purposes: https://<domain>/tenant-management/swagger-ui.html.

Endpoint Overview


To use this API for user management, you must have the required access permissions as mentioned below. This means that you must have specific authorizations. To use this API to create and delete tenants, you must be a system integrator.

Endpoints for Identity Provider Connection: idm-controller

The endpoints of the Identity Management Controller (idm-controller) provide an interface for retrieving user and role information from the connected identity provider.

They are provided by the TENANT-MANAGEMENT service.

In the default configuration, the endpoints are available for any user logged-in to yuuvis® Momentum.

HTTP Method
as of product version
PurposeResponse FormatDescription
GET
2021 Winter
whoAmIJSON

Retrieves the representation of the currently logged-in user.
/tenant-management/api/idm/me

GET
2021 Winter
getUsersJSON

Retrieves a list of all users within the same tenant as the currently logged-in user.
/tenant-management/api/idm/users

GET
2021 Winter
getUsersByRoleJSON

Retrieves a list of users that have the specified role assigned to them.
/tenant-management/api/idm/roles/{role}/users

GET
2021 Winter
getUserInfoJSON

Retrieves the representation of the user specified by id. Only users within the tenant of the logged-in user are available.
/tenant-management/api/idm/users/{id}

GET
2022 Spring
getRolesJSON

Gets all roles of the tenant of the requesting user.
/tenant-management/api/idm/roles

Endpoints for System Integrators: system-controller

These endpoints can be used for role, group and user management for a tenant and to create and delete tenants in Keycloak.

They are provided by the TENANT-MANAGEMENT service.

The access to the endpoints has to be limited to administrative users as specified with the permission for /tenant-management/api/system/** endpoints in the authentication-prod.yml configuration file.

The endpoints are used by the ARCHITECT Service that provides yuuvis® architect. If you want to use this service, do not change the default access condition that is matched with the YUUVIS_SYSTEM_INTEGRATOR role.

HTTP Method
as of product version
PurposeResponse FormatDescription

Manage Tenant Creation Profile

GET
2020 Winter
Retrieve the Keycloak System SettingsJSON

Retrieves the top-level representation of the identity provider Keycloak.
/tenant-management/api/system/info

POST
2020 Winter
Update the ProfileHTTP status code

Updates the tenant creation profile that is used while creating a tenant of a customer with all the information that should be set up, e.g., additional roles, users, schema and client settings. Each SaaS application has its own tenant creation profile.
/tenant-management/api/system/profile

GET
2020 Winter
Retrieve the ProfileJSON

Retrieves the profile data to be used when creating new tenants. Reads the tenant creation profile.
/tenant-management/api/system/profile


Manage Tenants

POST
2020 Winter
Create a TenantHTTP status code

Creates a new tenant with the values for the corresponding parameters specified in JSON format. Required settings for Keycloak and yuuvis® Momentum core are passed as well as custom (= product application) settings. 
/tenant-management/api/system/tenants

PUT
2020 Winter
Update the Data of a TenantHTTP status code

Update the data of the tenant specified by tenant.
/tenant-management/api/system/tenants/{tenant}

GET
2020 Winter
Retrieve the Tenant data JSON

Retrieves the top-level representation of the Keycloak realm specified by tenant. It will not include nested information like User and Client representations. Reads the tenant data of the specified tenant
/tenant-management/api/system/tenants/{tenant}

GET
2020 Winter
Retrieve the Data of all TenantsJSON

Retrieves the top-level representation of all realms. It will not include nested information like User and Client representations. Reads the list of all tenants. 
/tenant-management/api/system/tenants

DELETE
2020 Winter
Delete TenantJSON
PATCH
2021 Summer
UpdateTenantHTTP status code

Update a new tenant with the values for the corresponding parameters specified in JSON format.
/tenant-management/api/system/tenants/{tenant}

GET
2020 Winter
Retrieve the Number of UsersTXT

Retrieves the number of all users of the specified tenant
/tenant-management/api/system/tenants/{tenant}/users/count

POST
2020 Winter
Create  a UserJSON

Creates a new user with the given properties for the specified tenant.
/tenant-management/api/system/tenants/{tenant}/users

PUT
2020 Winter
Update the Data of a UserHTTP status code

Update the data of the user specified by tenant and id.
/tenant-management/api/system/tenants/{tenant}/users/{id}

GET
2020 Winter

Request a List of UsersJSON

Retrieves a list of all users of the specified tenant. As 2021 Autumn, the list can be filtered by applying query parameters.
/tenant-management/api/system/tenants/{tenant}/users

GET
2020 Winter
Retrieve the Data of a UserJSON

Retrieves the data of the user specified by tenant and id.
/tenant-management/api/system/tenants/{tenant}/users/{id}

DELETE
2020 Winter
Delete a UserHTTP status code

Deletes the user specified by id of the specified tenant.
/tenant-management/api/system/tenants/{tenant}/users/{id}

GET
2020 Winter
Retrieve the RolesJSON

Gets all roles of the specified tenant
/tenant-management/api/system/tenants/{tenant}/roles

POST
2021 Autumn
Create  a RoleJSON

Creates a new role for the specified tenant with the properties specified in JSON format in the request body.
/tenant-management/api/system/tenants/{tenant}/roles

DELETE
2021 Autumn
Delete a RoleJSON

Deletes the role specified by name for the specified tenant.
/tenant-management/api/system/tenants/{tenant}/role/{name}

GET
2021 Autumn
Retrieve the GroupsJSON

Retrieves all groups of the specified tenant with the assigned roles and members.
/tenant-management/api/system/tenants/{tenant}/groups

POST
2021 Autumn
Create  a GroupJSON

Creates a new group with the given properties for the specified tenant.
/tenant-management/api/system/tenants/{tenant}/groups

GET
2021 Autumn
Retrieve a GroupJSON

Retrieves the group specified by id of the specified tenant with the assigned roles and members.
/tenant-management/api/system/tenants/{tenant}/groups/{id}

PUT
2021 Autumn
UpdateGroupJSON

Updates the data of the group specified by id that is given for the specified tenant.
/tenant-management/api/system/tenants/{tenant}/groups/{id}

DELETE
2021 Autumn
Delete GroupHTTP status code

Deletes the group specified by id in the specified tenant.
/tenant-management/api/system/tenants/{tenant}/groups/{id}

GET
2021 Summer
Retrieve the Current Metrics JSONReads the current metrics of the specified tenant.
/tenant-management/api/system/tenants/{tenant}/metrics

Endpoints for Tenant Administrators: admin-controller

These endpoints can be used for role, group and user management in Keycloak within the own tenant. Administrative tenant-specific information can be retrieved as well.They are provided by the TENANT-MANAGEMENT service.

The access to the endpoints has to be limited to administrative users as specified with the permission for /tenant-management/api/admin/** endpoints in the authentication-prod.yml configuration file.

The endpoints are used by the ARCHITECT Service that provides yuuvis® architect. If you want to use this service, do not change the default access condition that is matched with the YUUVIS_TENANT_ADMIN role.

As of 2022 Autumn, in the default configuration, users with the YUUVIS_MANAGE_SETTINGS role are allowed to manage users of their own tenant as well. They have access to all endpoints /tenant-management/api/admin/users/**. However, the following operations are not allowed for them:

  • Assigning the YUUVIS_TENANT_ADMIN or YUUVIS_SYSTEM_INTEGRATOR roles.
  • Editing the data of users having the YUUVIS_TENANT_ADMIN or YUUVIS_SYSTEM_INTEGRATOR role.
  • Deleting users having the YUUVIS_TENANT_ADMIN or YUUVIS_SYSTEM_INTEGRATOR role.
HTTP Method
as of product version
PurposeResponse FormatDescription
GET
2020 Winter
Retrieve the Tenant data JSON

Retrieves the tenant data as given in the Keycloak identity provider for the tenant of the calling user.
/tenant-management/api/admin/tenant

GET
2020 Winter
Retrieve the Number of Users TXT

Retrieves the number of all users of the tenant.
/tenant-management/api/admin/users/count

POST
2020 Winter
CreateUserJSON

Creates a new user in the tenant with the given properties.
/tenant-management/api/admin/users

POST
2020 Winter
Create a User via CSVJSON

Creates users listed in a CSV-based file.
/api-tm/admin/users/batchcreate

Note: Keycloak does not offer an API for creating more than one user in one call. So you may want to create multiple users one by one by yourself.

GET
2020 Winter
Retrieve a UserJSON

Retrieves the data of the user specified by id.
/tenant-management/api/admin/users/{id}

PUT
2020 Winter
Update the Data of a UserHTTP status code

Updates the data of the user specified by id with the data passed in the request body in JSON format.
/tenant-management/api/admin/users/{id}

DELETE
2020 Winter
Delete a UserHTTP status code

Deletes the user specified by id.
/tenant-management/api/admin/users/{id}

GET
2020 Winter

Retrieve a List of UsersJSON

Retrieves a list of all users within the tenant. As 2021 Autumn, the list can be filtered by applying query parameters.
/tenant-management/api/admin/users

GET
2020 Winter
Retrieve the RolesJSON
POST
2021 Autumn
CreateRoleJSON

Creates a new role for the tenant with the properties specified in the JSON request body.
/tenant-management/api/admin/roles

DELETE
2021 Autumn
Delete a RoleJSON

Deletes the role specified by name.
/tenant-management/api/admin/role/{name}

GET
2021 Autumn
Retrieve the GroupsJSON

Retrieves all groups with the assigned roles and members for the tenant.
/tenant-management/api/admin/groups

POST
2021 Autumn
CreateGroupJSON

Creates a new group for the tenant with the properties specified in the JSON request body.
/tenant-management/api/admin/groups

GET
2021 Autumn
Retrieve a GroupJSON

Retrieves the group specified by id with the assigned roles and members for the tenant.
/tenant-management/api/admin/groups/{id}

PUT
2021 Autumn
UpdateGroupJSON

Updates the data of the group specified by id with the data passed in the request body in JSON format.
/tenant-management/api/admin/groups/{id}

DELETE
2021 Autumn
DeleteGroupJSON

Deletes the group specified by id.
/tenant-management/api/admin/groups/{id}

GET
2021 Spring
Retrieve the Current Metrics JSONReads the current metrics of the specified tenant.
/tenant-management/api/admin/metrics