Skip to main content
Version: 8.2505.x.x RR

nevisIDM Principal REST API

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.

IDM Principal Rest Service

Request token​

The client requests a token via POST to principal/v1/token. The grant_type has to be set to password.

**POST** principal/v1/token

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.

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

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

Accessing a protected resource​

To access a protected resource, the client has to include the token in the “X-Token” header of the request.

PATCH core/v1/1000/users/1223 HTTP/1.1
Host: server.example.com
X-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJleHRJZCIsImV4cCI6MTIzMTQxNH0.
DwrL243OOWVyqtn9_BzxEkca-VAlI6sQ9xwF23Boxy0

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 /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.

Self-admin​

Example URI​

GET https://your-host/nevisidm/api/principal/v1/me/

Response 200​

  • Headers: Content-Type: application/json
  • Body:
{
  "userExtId": "100",
  "loginId": "homersimpson",
  "fullName": "Homer J. Simpson",
  "email": "[email protected]",
  "displayLanguageCode": "EN",
  "clientExtId": "10000",
  "clientName": "Krusty Burger",
  "profileExtId": "230",
  "unitExtId": "221"
}

Token​

POST /token/ - Get Token

Generates a bearer token.

Self-admin​

Example URI​

POST https://your-host/nevisidm/api/principal/v1/token/

Request​

  • 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.
}

Response 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 /permissions/ - Get my permissions

Returns the elementary permissions of the user.

since 2.80 Self-admin​

Example URI​

GET https://your-host/nevisidm/api/principal/v1/permissions/

Request​

  • Headers: Content-Type: application/json

Response 200​

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