Tenant Management Endpoints
- Technische Redaktion
- Team Kolibri (Unlicensed)
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 | Purpose | Response Format | Description |
|---|---|---|---|
| GET 2021 Winter | whoAmI | JSON | Retrieves the representation of the currently logged-in user. |
| GET 2021 Winter | getUsers | JSON | Retrieves a list of all users within the same tenant as the currently logged-in user. |
| GET 2021 Winter | getUsersByRole | JSON | Retrieves a list of users that have the specified |
| GET 2021 Winter | getUserInfo | JSON | Retrieves the representation of the user specified by |
| GET 2022 Spring | getRoles | JSON | Gets all roles of the tenant of the requesting user. |
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 | Purpose | Response Format | Description |
|---|---|---|---|
Manage Tenant Creation Profile | |||
| GET 2020 Winter | Retrieve the Keycloak System Settings | JSON | Retrieves the top-level representation of the identity provider Keycloak. |
| POST 2020 Winter | Update the Profile | HTTP 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. |
| GET 2020 Winter | Retrieve the Profile | JSON | Retrieves the profile data to be used when creating new tenants. Reads the tenant creation profile. |
Manage Tenants | |||
| POST 2020 Winter | Create a Tenant | HTTP 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. |
| PUT 2020 Winter | Update the Data of a Tenant | HTTP status code | Update the data of the tenant specified by |
| GET 2020 Winter | Retrieve the Tenant data | JSON | Retrieves the top-level representation of the Keycloak realm specified by |
| GET 2020 Winter | Retrieve the Data of all Tenants | JSON | 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. |
| DELETE 2020 Winter | Delete a Tenant | JSON | Deletes the specified |
| PATCH 2021 Summer | Update a Tenant | HTTP status code | Update a new tenant with the values for the corresponding parameters specified in JSON format. |
| GET 2020 Winter | Retrieve the Number of Users | TXT | Retrieves the number of all users of the specified |
| POST 2020 Winter | Create a User | JSON | Creates a new user with the given properties for the specified tenant. |
| PUT 2020 Winter | Update the Data of a User | HTTP status code | Update the data of the user specified by |
GET | Request a List of Users | JSON | Retrieves a list of all users of the specified |
| GET 2020 Winter | Retrieve the Data of a User | JSON | Retrieves the data of the user specified by |
| DELETE 2020 Winter | Delete a User | HTTP status code | Deletes the user specified by |
| GET 2020 Winter | Retrieve the Roles | JSON | Gets all roles of the specified |
| POST 2021 Autumn | Create a Role | JSON | Creates a new role for the specified tenant with the properties specified in JSON format in the request body. |
| DELETE 2021 Autumn | Delete a Role | JSON | Deletes the role specified by |
| GET 2021 Autumn | Retrieve the Groups | JSON | Retrieves all groups of the specified |
| POST 2021 Autumn | Create a Group | JSON | Creates a new group with the given properties for the specified tenant. |
| GET 2021 Autumn | Retrieve a Group | JSON | Retrieves the group specified by |
| PUT 2021 Autumn | Update a Group | JSON | Updates the data of the group specified by id that is given for the specified tenant. |
| DELETE 2021 Autumn | Delete a Group | HTTP status code | Deletes the group specified by |
GET deprecated as of 2023 Autumn | Retrieve the Current Metrics | JSON | Reads 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 | Purpose | Response Format | Description |
|---|---|---|---|
| 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. |
| GET 2020 Winter | Retrieve the Number of Users | TXT | Retrieves the number of all users of the tenant. |
| POST 2020 Winter | Create a User | JSON | Creates a new user in the tenant with the given properties. |
| POST 2020 Winter | Create a User via CSV | JSON | Creates users listed in a CSV-based file. 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 User | JSON | Retrieves the data of the user specified by |
| PUT 2020 Winter | Update the Data of a User | HTTP status code | Updates the data of the user specified by |
| DELETE 2020 Winter | Delete a User | HTTP status code | Deletes the user specified by |
GET | Retrieve a List of Users | JSON | Retrieves a list of all users within the tenant. As 2021 Autumn, the list can be filtered by applying query parameters. |
| GET 2020 Winter | Retrieve the Roles | JSON | Gets all roles. |
| POST 2021 Autumn | Create a Role | JSON | Creates a new role for the tenant with the properties specified in the JSON request body. |
| DELETE 2021 Autumn | Delete a Role | JSON | Deletes the role specified by |
| GET 2021 Autumn | Retrieve the Groups | JSON | Retrieves all groups with the assigned roles and members for the tenant. |
| POST 2021 Autumn | Create a Group | JSON | Creates a new group for the tenant with the properties specified in the JSON request body. |
| GET 2021 Autumn | Retrieve a Group | JSON | Retrieves the group specified by |
| PUT 2021 Autumn | Update a Group | JSON | Updates the data of the group specified by |
| DELETE 2021 Autumn | Delete a Group | JSON | Deletes the group specified by |
GET deprecated as of 2023 Autumn | Retrieve the Current Metrics | JSON | Reads the current metrics of the specified tenant./tenant-management/api/admin/metrics |