Back to top

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

**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 fields. 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 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 info
GET/me/

Returns information about the actual user. Used to display basic information about the user without having to query many different resources.

Selfadmin

Example URI

GET https://your-host/nevisidm/api/principal/v1/me/
Response  200
HideShow
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 token
POST/token/

Generates a bearer token.

Selfadmin

Example URI

POST https://your-host/nevisidm/api/principal/v1/token/
Request
HideShow
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
}
Response  200
HideShow
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
}

Generated by aglio on 11 Feb 2020