nevisIDM Principal REST API (v1)
Introduction
The nevisIDM Principal REST API provides security-related features. Contrary to the REST API, these resources cannot be directly mapped to business objects.
Principal REST service ¶
This service is supposed to return personal information about the actual user, and to generate security tokens. The nevisIDM Principal REST API is an individual API. Its versioning is independent from other APIs.
Password-based verification with tokens
Certain resource parameter values are protected. Such a protected parameter value can be, for example, the email address or status of the user. If a user wants to modify a protected resource parameter value, the server first asks for the password of the user. If the password was correct, the server issues a temporary token. As long as the token is valid, the user does not have to type the password again. The user can also modify other protected parameters. Once the token expires, the user has to re-enter their password.

Request token
The client requests a token via POST to “principal/v1/token”. The “grant_type” has to be set to “password”.
Response
A successful response returns with status code 200 (“OK”). The response includes the HTTP “Cache-Control” and “Pragma” response header parameters. They are set to “no-store” and “no-cache”, respectively.
Accessing a protected resource
To access a protected resource, the client has to include the token in the “X-Token” header of the request.
Errors
In case of an invalid, missing or expired token/password, the server returns an “Error 401” response, including human-/client-readable content about the missing or invalid password or token. Error 401 (“Unauthorized”) is similar to Error 403 (“Forbidden”), but specifically used when authentication is required and failed, or has not yet been provided. The response includes a “WWW-Authenticate” header parameter containing a challenge applicable to the requested resource.
Permissions
The caller has to be authenticated. No special permissions are needed.
Me ¶
Get my infoGET/me/
Returns information about the actual user. Used to display basic information about the user without having to query many different resources.
Example URI
200
Headers
Content-Type: application/json
Body
{
"userExtId": "100",
"loginId": "homersimpson",
"fullName": "Homer J. Simpson",
"email": "asdf@asdf.com",
"displayLanguageCode": "EN",
"clientExtId": "10000",
"clientName": "Krusty Burger",
"profileExtId": "230",
"unitExtId": "221"
}
Token ¶
Get tokenPOST/token/
Generates a bearer token.
Example URI
Headers
Content-Type: application/json
Body
{
"grant_type": string, // Value has to be set to "password".
"username": string, // loginId of the user, which has to be the same as the one of the caller.
"password": string // Value of the password.
}
200
Headers
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
Body
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleHRJZCIsImV4cCI6MTIzMTQxNH0.DwrL243OOWVyqtn9_BzxEkca-VAlI6sQ9xwF23Boxy0",
"token_type": "bearer",
"expires_in": 3600
}
Permissions ¶
Get my permissionsGET/permissions/
Returns the elementary permissions of the user.
Example URI
Headers
Content-Type: application/json
200
Body
{
"elementaryPermissions": [
"AccessControl.ConsentView",
"AccessControl.SelfAdmin",
"AccessControl.CredentialView",
"AccessControl.ClientView"
]
}