• Person API
  • API 1 Create a person
  • API 2 Fetch person info
  • API 3 Update a person
  • API 4 Delete a person
  • API 5 Invite a person
  • API 6 Block a person
  • API 7 Unblock a person
  • API 8 Set custom person attribute
  • API 9 Update custom person attributes (or merge with ADD)
  • API 10 Delete custom person attributes
  • API 11 Trigger a password reset for a person
  • API 12 Search Persons
    • Search by email address
    • Search by phone number
    • Search by custom attribute
    • Search by last modification date
    • Result
  • API 13 Reset a person
  • API 14 Sign up a person
  • API 15 Change password for person
    • Change password with current password verification
    • Change password without current password verification
    • Password encryption
    • Common errors on password change
  • API 16 Create person and automatically signup
  • API 17 Couple account with External IDP
  • API 18 Fetch person profile
  • API 19 Fetch multiple persons profiles

Person API

This document describes the API operations for a person. A person is basically a user account in Onegini IDP. Some of the operations should typically be used by a helpdesk or a CRM application.

API 1 Create a person

Endpoint: POST /api/persons

The body includes a Profile object as defined in the Onegini Java SDK. The table below denotes the required fields:

Information

Admin panel contains additional configuration options that can influence to described fields.

1. Invitation email is sent after creating a person so each fields selected in section Configuration -> Invitation verification is required during create person api call, eg. birth date, mobile number or addresses.
2. Admin can check some fields as required in section Configuration -> Attributes mandatory on person creation, eg. mobile number.

When a person was successfully created an HTTP 201 CREATED message is returned with a JSON body including the reference_id of the user within Onegini IDP.

{
    "reference_id":"1234567890ABC"
}

Error messages do have an error code plus a small description. The following errors can occur.

API 2 Fetch person info

Details of a person can be fetched via its person_id.

Endpoint: GET /api/persons/{person_id}

When a person was found for the provided identifier an HTTP 200 OK message is returned with the below denoted response body. The Profile object in the API is used from the Onegini Java SDK.

{
  "person_id": "08f831ab-a22f-4159-a851-15eec46c3717",
  "profile": {
    "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,
        "tag": "ALTERNATIVE",
        "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"
      },
      {
        "primary": false,
        "street_name": "Main Street",
        "house_number": 1,
        "postal_code": "01A A34",
        "city": "Mytown",
        "country_code": "GB"
      }
    ],
    "custom_attributes": [
      {
        "name": "myCRM",
        "value": "ABC123DEF456"
      }
    ],
    "preferred_locale": "en_GB"
  },
  "events": [
    {
      "occurred": 1409145076543,
      "event_type": "person.PersonCreatedEvent",
      "event_name": "Person Created",
      "person_id": "08f831ab-a22f-4159-a851-15eec46c3717",
      "client_ip": "192.168.10.30",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.9; rv:31.0) Gecko/20100101 Firefox/31.0"
    },
    {
      "occurred": 1409145080692,
      "event_type": "person.PinStoredEvent",
      "event_name": "PIN created",
      "person_id": "08f831ab-a22f-4159-a851-15eec46c3717",
      "client_ip": "192.168.10.30",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.9; rv:31.0) Gecko/20100101 Firefox/31.0"
    }
  ],
  "creation_date": 1409143076543,
  "status": "BLOCKED",
  "blocked_reason": "Reason why person is blocked",
  "last_login": 1409145076543,
  "logins ": 25,
  "identity_providers": [
    {
      "name": "Username & Password",
      "status": "ACTIVATED",
      "last_login": 1409145076543
    },
    {
      "name": "Google",
      "status": "ACTIVATED",
      "last_login": 1409145074367
    }
  ]
}

Below are extra details about some of the fields from the response:

The following errors can occur

API 3 Update a person

A person can be updated via its person_id

Endpoint: PUT /api/persons/{person_id}

The body of the request contains a profile object with the updated fields. For example to update a name:

{
  "name": {
    "first_name": "My",
    "last_name": "New Name",
    "initials": "N"
  }
}

Only fields mentioned in the profile object are updated. When updating email, phone number or addresses only the primary is updated. For custom_attributes the complete collection will be replaced.

The following fields can be updated:

• Gender
• Name
• Date of Birth
• Addresses (collection)
• Preferred Locale
• Email addresses (collection)
• Phone numbers (collection)
• Custom attributes (collection)

For a successful update request an HTTP 204 No Content response is returned.

The following errors can occur

API 4 Delete a person

A person can be deleted via its person_id.

Endpoint: DELETE /api/persons/{person_id}

Optionally a reason can be specified why the person is deleted. This is done via a json object in the body of the request.

{
    "reason": "Reason why person is deleted"
}

The response will be an HTTP 204 No Content when the person was successfully removed.

The following errors can occur

API 5 Invite a person

A person can be invited by its person_id. The method used to send the invitation is already set for a person.

Endpoint: POST /api/persons/{person_id}/invite

The response will be an HTTP 201 CREATED with a JSON response including a profile object with only the reference_id of the person the invitation was sent to.

{
    "reference_id": "08f831ab-a22f-4159-a851-15eec46c3717"
}

The following errors can occur

API 6 Block a person

Endpoint: POST /api/persons/{person_id}/block

Optionally a reason can be specified why the person is blocked. This is done via a json object in the body of the request. When no reason is specified an empty JSON body is expected.

{
    "reason": "Reason why person is blocked"
}

The response will be an HTTP 204 No Content when the person was successfully blocked.

The following errors can occur

API 7 Unblock a person

Endpoint: POST /api/persons/{person_id}/unblock

The response will be an HTTP 204 No Content when the person was successfully blocked.

The following errors can occur

API 8 Set custom person attribute

Identifiers for external systems are stored in the custom attributes container. A custom attributes objects contains a name and a value.

Endpoint: POST /api/persons/{person_id}/custom-attributes

The request has a JSON body containing a custom attribute object.

{
  "name":"myCRM",
  "value":"ABC123DEF456"
}

The response will be an HTTP 204 No Content when the identifier was successfully added.

The following errors can occur

API 9 Update custom person attributes (or merge with ADD)

Endpoint: PUT /api/persons/{person_id}/custom-attributes

The request has a JSON body

{
  "name":"myCRM",
  "value":"ABC123DEF456"
}

The response will be an HTTP 204 No Content when the identifier was successfully updated.

The following errors can occur

API 10 Delete custom person attributes

To delete an identifier the system name is used to identify the custom attribute within the users custom attributes.

Endpoint: DELETE /api/persons/{person_id}/custom-attributes/{attribute_name}

The response will be an HTTP 204 No Content when the identifier was successfully added.

The following errors can occur

API 11 Trigger a password reset for a person

Endpoint: POST /api/persons/{person_id}/password-reset

The response will be an HTTP 204 No Content when the password reset was successfully triggered.

The request may contain optional JSON body

{
  "redirect_url": "http://example.com"
}

If the reset password request contains a redirect_url parameter, the user will be redirected to this URL after finishing the password reset procedure

Error messages do have an error code plus a small description. The following errors can occur

API 12 Search Persons

Endpoint: GET /api/persons/search

The response will be an HTTP 200 OK even if no persons are found.

The endpoint allows to search for users using two methods:

• search by email address
• search by custom attribute

Error messages do have an error code plus a small description. The following errors can occur:

Search by email address

Users can be found via their email address.

Exact match

Example: /api/persons/search?email_address=johndoe%40bar.com

Searching on an exact email address can return at most 1 person in the search result.

Partial match

Set the partial_match request parameter to true for advanced lookup of a user.

Example: /api/persons/search?email_address=johndoe&partial_match=true&offset=0&limit50

This method will first look up the person for the given email_address. If no person is found, it searches for all persons that have an email address that starts with the given email_address.

For search term johndoe it returns the users with email addresses [email protected] or [email protected] but not [email protected].

This method can return multiple persons in the search result.

Search by phone number

Users can be found via their phone number.

Example: /api/persons/search?phone_number=%2B311234567890

Phone number must be normalized according to E.164 standard. Phone number must not contain spaces, dashes and any other additional characters. Phone number must contain country code and must start with + sign decoded for URL into %2B.

This method may return multiple profiles in the search result.

Search by custom attribute

Search by custom attribute takes the following form:

/api/persons/search?custom_attribute:foo=bar

This will search for all persons with a custom attribute that has the name foo and value bar.

Custom attributes are not unique, and therefore multiple persons can be returned.

Search by last modification date

Person search API gives possibility to search by last modification date:

It is also possible to use additional properties for customization:

By default response contain email address and reference id (person id) attributes but it is possible to return only part of it by using following property:

Example requests:

• GET /api/persons/[email protected]
  will return persons that exactly match email address [email protected]
• GET /api/persons/[email protected]&last_modified=1481010950
  will return persons that match email address [email protected] and last modified after 1477958400 (11/01/2016 @ 12:00am)
• GET /api/persons/search?last_modified=1481010950&include_fields=reference_id,email_addresses
  will return persons that were last modified after 1477958400 (11/01/2016 @ 12:00am) and include only person id and email addresses in the result

Restricitons

Request that contains last_modified parameter will return only email addresses and reference id. Other attributes like name, phone_numbers, etc. are not currently supported by this parameter and will not be returned.

Result

{
    "resultSet": [
        {
            "name": {
                "first_name": "John",
                "last_name": "Snow",
                "display_name": "John Snow"
            },
            "email_addresses": [
                {
                    "primary": true,
                    "tag": "",
                    "verified": false,
                    "value": "[email protected]"
                }
            ],
            "phone_numbers": [
                {
                    "primary": true,
                    "tag": "MOBILE",
                    "value": "+49712129815"
                }
            ],
            "custom_attributes": [
              {
                    "name":"foo",
                    "value":"bar"
              }
            ],
            "preferred_locale": "nl",
            "reference_id": "3ba13d11-2e4b-49fa-ade6-5a18e448ae2b"
        }
    ],
    "pagination": {
        "totalResults": 1,
        "offset": 0,
        "pageSize": 0
    }
}

API 13 Reset a person

A person which already has an activated account can be deactivated via the reset person functionality. After a person is reset a new invitation can be send. The existing identities of the person will be removed.

Endpoint: POST /api/persons/{person_id}/reset

The response will be a HTTP 204 NO CONTENT when the operation was successful.

The following errors can occur

API 14 Sign up a person

After creating a person via API 1 Create Person, the account is not ready to use. In this Sign up call, the person's credentials are set and the account is activated. The mechanism to encrypt the password is described in the documentation of the Password Encryption.

Endpoint: POST /api/persons/{person_id}/sign-up

The request has a JSON body

{
  "password": "+V7wn+NyMG7cVelxIIiJYrUkqJiNDJRsqw==",
  "encryption_parameter": "+V7wNOIFDSYo8yhsfdhSAh9asdfDJRsqw=="
}

The response will be a HTTP 204 NO CONTENT when the operation was successful.

The following errors can occur

API 15 Change password for person

There are two actions which can be used in order to change user's password. First one, change password, requires user's current as well as new passwords to be provided within the API call. Second, set password, requires only new password and is intended to be used for service purposes by superusers.

Change password with current password verification

Password can be changed by sending json request with these parameters:

• password: current user password (should be sent in encrypted form)
• new_password: new user password (should be sent in encrypted form)
• encrypted_parameter: initialization vector used by encryption algorithm

Endpoint: POST /api/persons/{person_id}/password-change

The request has a JSON body

{
  "password": "+V7wn+NyMG7cVelxIIiJYrUkqJiNDJRsqw==",
  "new_password": "+V7wn+NNOIFDxIIiJYrUkqJNOIFDD==",
  "encryption_parameter": "+V7wNOIFDSYo8yhsfdhSAh9asdfDJRsqw=="
}

The response will be a HTTP 204 NO CONTENT when the operation was successful.

The following custom error may occurs

Change password without current password verification

Password can be set by sending json request with these parameters:

• password: new password (should be sent in encrypted form)
• encrypted_parameter: initialization vector used by encryption algorithm

Endpoint: POST /api/persons/{person_id}/set-password

The request has a JSON body

{
  "password": "+V7wn+NyMG7cVelxIIiJYrUkqJiNDJRsqw==",
  "encryption_parameter": "+V7wNOIFDSYo8yhsfdhSAh9asdfDJRsqw=="
}

The response will be a HTTP 204 NO CONTENT when the operation was successful.

Password encryption

The mechanism to encrypt the password is described in the documentation of the Password Encryption.

Common errors on password change

The following common errors can occur on password change

API 16 Create person and automatically signup

Endpoint: POST /api/persons/activated

API allows to create a new signed-up user by executing a single request. It can be achieved by calling /api/persons/activated endpoint.

The body includes json object that is composed from Profile and EncryptedPassword objects as defined in the Onegini Java SDK The mechanism to encrypt the password is described in the documentation of the Password Encryption. The table below denotes the required fields:

When a person was successfully created and signup an HTTP 201 CREATED message is returned with a JSON body including the reference_id of the user within Onegini IDP.

The following errors can occur

Example request:

POST /api/persons/activated HTTP/1.1
Host: example.org
Content-Type: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

{
  "encrypted_password": 
  {
    "password": "o/MCR6uS/RAmOse1+3ngU6gjf/+r8h4xWw==",
    "encryption_parameter": "BVLdWx//evkFUt1bH/96+Q==",
    "new_password": "o/MCR6uS/RAmOse1+3ngU6gjf/+r8h4xWw=="
  },
  "profile":
  {
    "email_addresses":[
      {
              "primary": true,
              "tag": "",
              "verified": false,
              "value": "[email protected]"
            }
        ]
  }
}

Example response:

HTTP 201
{"reference_id":"0cd77022-4111-41eb-8c1c-e0f46c8a30ae"}

API 17 Couple account with External IDP

API allows to couple idp account with external IDP. It requires to pass person id in the url and external idp data required for coupling.

Endpoint: POST /api/persons/{person_id}/couple

The request is a JSON body:

{
  "idp_type": "kerberos",
  "external_idp_id": "12345-12345-12345-12345"
}

Body parameters:

Response on success:

HTTP 201 Created is returned on success without additional information in body.

Response on error:

Error response contains error code and description. Example:

{
  "error_code": "1006"
  "error_message": "No person can be found based on the specified identifier."
}

The following errors may occur:

API 18 Fetch person profile

Fetching person profile is possible by calling /api/persons/{person_id}/profile endpoint and providing person_id variables within the request path:

Endpoint: GET /api/persons/{person_id}/profile

When a person with specified identifier is found an HTTP 200 OK is returned with the below denoted response body. The Profile object in the API is used from the Onegini Java SDK.

{
  "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,
      "tag": "ALTERNATIVE",
      "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"
    },
    {
      "primary": false,
      "street_name": "Main Street",
      "house_number": 1,
      "postal_code": "01A A34",
      "city": "Mytown",
      "country_code": "GB"
    }
  ],
    "custom_attributes": [
      {
        "name": "myCRM",
        "value": "ABC123DEF456"
      }
    ],
    "preferred_locale": "en_GB"
  ]
}

The following errors can occur:

API 19 Fetch multiple persons profiles

Fetching profiles objects for multiple persons is possible by calling /api/persons/bulk/{person_id}/profile endpoint and providing multiple, comma delimited person_id variables within the request path:

Endpoint: GET /api/persons/bulk/{person_id},{another_person_id}/profile

When all person were found for the provided identifiers an HTTP 200 OK is returned with the below denoted response body. The Profile object in the API is used from the Onegini Java SDK.

{
  "resultSet": [
    {
      "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,
          "tag": "ALTERNATIVE",
          "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"
        },
        {
          "primary": false,
          "street_name": "Main Street",
          "house_number": 1,
          "postal_code": "01A A34",
          "city": "Mytown",
          "country_code": "GB"
        }
      ],
        "custom_attributes": [
          {
            "name": "myCRM",
            "value": "ABC123DEF456"
          }
        ],
        "preferred_locale": "en_GB"
      ]
    },
    {
      "name": {
        "first_name": "Test",
        "last_name": "User",
        "display_name": "Test User"
      },
      "email_addresses": [
        {
          "primary": true,
          "tag": "",
          "verified": false,
          "value": "[email protected]"
        }
      ],
      "phone_numbers": [
        {
          "primary": true,
          "tag": "MOBILE",
          "value": "+01123456789"
        }
      ],
      "preferred_locale": "nl"
    }
  ],
  "pagination": {
    "totalResults": 2,
    "offset": 0,
    "pageSize": 0,
    "rangeStart": 1,
    "rangeEnd": 0,
    "firstPage": true,
    "lastPage": true,
    "numberOfPages": 0,
    "visiblePages": []
  }
}

The following errors can occur: