REST guidelines

In this section REST guidelines are stated. Communication between the service calling the provided API and Onegini IdP is implemented using REST.

Profile

The profile object from the Onegini Java SDK is used in some of the API’s below is an example.

{
  "gender": "M",
  "name": {
    "first_name": "John",
    "last_name": "Doe",
    "initials": "J",
    "display_name": "John J Doe Jr, MSc"
  },
  "date_of_birth": "1995-05-24",
  "email_addresses": [
    {
      "primary": true,
      "value": "[email protected]"
    },
    {
      "primary": false,
      "value": "[email protected]",
      "tag": "BUSINESS"
    },
    {
      "primary": false,
      "value": "[email protected]",
      "verified": true
    }
  ],
  "phone_numbers": [
    {
      "primary": true,
      "value": "+12125551234",
      "tag": "MOBILE"
    },
    {
      "primary": false,
      "value": "+3160123456"
    }
  ],
  "addresses": [
    {
      "primary": true,
      "street_name": "Pompmolenlaan",
      "house_number": 9,
      "house_number_addition": "2nd floor",
      "postal_code": "3447 GK",
      "city": "Woerden",
      "region": "Utrecht",
      "country_code": "NL",
      "company_name": "Onegini",
      "attention": "John Doe"
    }
  ],
  "custom_attributes": [
    {
      "name":"myCRM",
      "value":"ABC123DEF456"
    }
  ],
  "preferred_locale": "en_GB"
}

Stateless communication

The communication between the service calling the API and Onegini IdP is stateless.

Non cacheable communication

The communication between the service calling the API and Onegini IdP is not cacheable. Onegini IdP will mark the communication as being so:

Cache-Control: no-store
Pragma: no-cache

JSON

The service using the API can use JSON to communicate with Onegini IdP. To receive JSON messages another header must be added:

Accept: application/json

UTF-8 encoding

Onegini IdP uses UTF-8 encoding:

Content-Type: application/json;charset=UTF-8

Generic error response

When an error occurs in the API a general JSON error response is returned. The response is denoted below:

{
    "error_code":"1001",
    "error_message":"Registration not available"
}

Bad request error response

In case the API call is missing some of the parameters or the one provided do not match expected type the application will respond with 400 BAD REQUEST and following body:

{
    "error_code":"1041",
    "error_message":"The request received by the server was invalid or malformed"
}

Security

All APIs are protected with HTTP basic authentication.

The Authorization header needs to be added every request.

The Authorization header is constructed as follows: 1. Username and password are combined into a string "username:password" 2. The resulting string is then encoded using the RFC2045-MIME variant of Base64, except not limited to 76 char/line 3. The authorization method and a space i.e. "Basic " is then put before the encoded string.

For example, if the user agent uses 'Aladdin' as the username and 'open sesame' as the password then the header is formed as follows:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Metadata

Events are stored for state changes in Onegini IdP. These events can contain meta data about the request that triggered this change.

The following HTTP request headers are not stored as meta data for security reasons:

• authorization
• cookie
• proxy-authorization

Extra audit information

The custom HTTP headers x-onegini-api-agent-user and x-onegini-api-agent-app can be used to store the identifier of the person and application that caused the API call.

Examples:

• user identifier or name of a customer service agent that triggers password reset or changes the e-mail address for an end-user
• identifier of the application that creates or deletes accounts based on data in an external system

Additional API configuration

The custom HTTP header X-Onegini-Api-Configuration can be used to modify IDP configuration in API request context only. Currently following options are supported:

userNotificationEnabled - allows to disable email notifications on Person API updates.

Example

X-Onegini-Api-Configuration: userNotificationEnabled=false

Concurrent requests to API

Please note that currently concurrent requests to API that relate to the same person are not supported. In case it's necessary to perform multiple API calls for the same person, please execute them sequentially.