nevisIDM Principal REST API (v1)

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.

Content-Type: application/json

{
  "userExtId": "100",
  "loginId": "homersimpson",
  "fullName": "Homer J. Simpson",
  "email": "asdf@asdf.com",
  "displayLanguageCode": "EN",
  "clientExtId": "10000",
  "clientName": "Krusty Burger",
  "profileExtId": "230",
  "unitExtId": "221"
}

Content-Type: application/json

{
 "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.
}

Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleHRJZCIsImV4cCI6MTIzMTQxNH0.DwrL243OOWVyqtn9_BzxEkca-VAlI6sQ9xwF23Boxy0",
  "token_type": "bearer",
  "expires_in": 3600
}

Content-Type: application/json

{
  "elementaryPermissions": [
    "AccessControl.ConsentView",
    "AccessControl.SelfAdmin",
    "AccessControl.CredentialView",
    "AccessControl.ClientView"
  ]
}