nevisIDM _principal_ REST API (v1)
Introduction
This API is used to provide 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. This is an individual API. Its versioning is independent from other APIs.
Password-based verification with tokens
Certain resource field values are protected. Such a protected field value can be e.g. a user’s email address or status. If a user wants to modify a protected resource field value, the server first asks for the user’s password. 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. He is also able to modify other protected fields. Once the token expires, the user has to re-enter his 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 fields. 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 has failed or has not yet been provided. The response includes a “WWW-Authenticate” header field containing a challenge applicable to the requested resource.
Permissions
No special permissions are needed but the caller has to be authenticated.
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 MUST be set to "password".
"username": string, // loginId of the user. 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
}