Realms management via REST services

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}'

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.