---
title: "Realms management via REST services"
canonical: "https://onesaitplatform.refined.site/space/DOCT/2220848405/Realms%20management%20via%20REST%20services"
format: markdown
---
EN |  ES In order to use these services, you must be previously authenticated in the platform with OAuth2, as you need to provide a Bearer token as the header for every endpoint. Endpoints start with ' /controlpanel/api/realms'.  You can take a look at all API endpoints in the swagger UI:  /controlpanel/swagger-ui.html#RealmManagement 1. GET  1.1. Realm retrieval To retrieve realms information, you can either use  GET method   by realm   identification,  or  GET  a list of all realms. By realm identification:   GET '/controlpanel/api/realms/{identification}' The response body contains a JSON with attributes that represent the realm's info, such as identification, name, description, roles, users and associations with other realms. Administrator users can get information of all registered Realms on the platform. If the user hasn´t administrator role, only her own Realms will be available. GET all:   GET '/controlpanel/api/realms'   As above, administrators user will get a list with all availables Realms on the platform. The rest of users will get a list with the Realms they owned. 1.2. Realm Roles retrieval A user can retrieve a list of realm roles by sending   GET request to '/controlpanel/api/realms/{identification}/roles' Administrator users can obtain any Platforms Realm's Role's list. Other users can only retrieve the information of the Realms they owned. 1.3. Realm Users retrieval You can also retrieve users that are authorized in a realm: By user id:   GET '/controlpanel/api/realms/{identification}/users/{userid} Then you will get the user's info: Administrator users can get information of all registered Realms on the platform. If the user hasn´t administrator role, only her own Realms will be available. All :  GET '/controlpanel/api/realms/{identification}/users' Administrator users can obtain any Platforms Realm's registerd users list. Other users can only retrieve the information of the Realms they owned. 2. POST 2.1.Realm creation To create a realm, you must specify the attributes below: The  roles  attribute is an array of objects. Each role has a name and a description. Users and associations must be declared after the realm's creation. As additional information you can register the Realm's secret, and the Realm's token's validity period of time. Example:   POST '/controlpanel/api/realms' 2.2. Realm Role creation  If you want to create additional roles that were not specified when the realm was created, you can create new roles making a   POST   request to: POST '/controlpanel/api/realms/{realmid}/roles' The user must be the Realm's owner or has administrator role. 2.3. Realm User authorization/association creation To add users to a Realm, the Realm role and the user must exist. Then you can create the relationship through: POST '/controlpanel/api/realms/authorization' To associate users to any realm, the user has to be the Realm's owner or to be a platform's administrator (a user with administrator role). 2.4. Realms association creation As stated in other sections, you can make relationships between roles of different realms. To achieve this, you must declare the parent role and child role, as well as their respective realms. Make a   POST   request to   '/controlpanel/api/realms/association' For Associating Realms it will be necessary the user to own both Realms, or to be a platform's administrator (an user with administrator role). 3. PUT 3.1. Updating a Realm For back-end complexity reasons, you can only update the realm's name and description. Roles, users, and associations have to be updated by their respective endpoints. Example:  PUT '/controlpanel/api/realms/{id}' For these operations, for now, you need to delete and create new entities, since the PUT operation is not implemented.  Only owners and administrator users can modify Realms. 3.2. Realm User, Realm authorization, Realm association Update For these operations, as of now, you must delete and create new items, because PUT operation is not yet implemented. 4. DELETE 4.1. Deleting a Realm If you want to delete a realm and its associations, make a   DELETE   request to   ' /controlpanel/api/realms/{realmid}' To delete a realm, the user has to be the Realm's owner or to be a platform's administrator (a user with administrator role). 4.2. Deleting a Realm's role If you want to delete a realm's role, you can make a   DELETE   request to  '/controlpanel/api/realms/{realmid}/roles/{roleName}' As in the previous case, a Realm's role can only be deleted by the Realm's owner or by an administrator user. 4.3. Realm Registered User delete To remove a user from a Realm, you must delete the user's authorization to that realm. This is achieved by making a   DELETE   request to endpoint   '/controlpanel/api/realms/authorization/realm/{realmid}/user/{userid}' This operation can only be done by the Realm's owner user or by an administrator user. 4.4. Realms Association delete To delete an association between two realms, you must specify parent realm and role, as well as child realm and role. DELETE '/controlpanel/api/realms/association/parent-realm/{parentRealmId}/parent-role/{parentRoleName}/child-realm/{childRealmId}/child-role/{childRoleName} To delete an association, the user must be the Realm's owner or an administrator user.