Person API

Overview

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.

Version information

Version : 1.0.0

Paths

Check if user exists in idp or extension

POST /api/migration/status

Parameters

Type Name Description Schema
Header X-Onegini-Flow-Context-Params
optional
Additional flow context parameters.

Allowed format is "key1=value1;key2=value2"
string
Header X-Onegini-Persons-Partition-Id
optional
Partition id for the user to be validated, required when persons partitioning feature is enabled string
Body email
required
User search criteria SearchUserRequestBody

Responses

HTTP Code Description Schema
200 A json object with search status SearchUserResponseBody
400 One of required parameters is missing No Content
401 When Basic Auth credentials are missing No Content
503 When migration feature is disabled but person api is enabled No Content

Consumes

  • application/json

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/migration/status
Request header
"string"
Request body
{
  "email" : "john@example.com"
}

Example HTTP response

Response 200
{
  "status" : "string",
  "person_id" : "2091f05b-2177-3ec8-8e1b-fdddbd5dc523"
}

Create a person

POST /api/persons

Description

Creates person with given details. If person activation is enabled, person is not activated

Parameters

Type Name Description Schema
Header X-Onegini-Flow-Context-Params
optional
Additional flow context parameters.

Allowed format is "key1=value1;key2=value2"
string
Header X-Onegini-Persons-Partition-Id
optional
Partition id for the user to be validated, required when persons partitioning feature is enabled string
Body Profile
required
Person's to create profile. Profile

Responses

HTTP Code Description Schema
201 Person created successully Person
400 Bad request ErrorResponse
409 Email address conflict ErrorResponse
503 Feature not available ErrorResponse

Consumes

  • application/json

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/persons
Request header
"string"
Request body
{
  "gender" : "M",
  "name" : {
    "first_name" : "John William",
    "last_name" : "Doe",
    "initials" : "J.W.D",
    "display_name" : "Mr John W. Doe, Msc."
  },
  "date_of_birth" : "1995-05-24",
  "email_addresses" : [ {
    "primary" : true,
    "verified" : false,
    "value" : "john.doe@onegini.com"
  } ],
  "phone_numbers" : [ {
    "primary" : true,
    "verified" : true,
    "value" : "+31 654 321 098"
  } ],
  "addresses" : [ {
    "house_number" : 9,
    "house_number_addition" : "2nd floor, 101",
    "street_name" : "Main street",
    "city" : "Woerden",
    "postal_code" : "1000 AA, 12345-6789",
    "region" : "Utrecht",
    "country_code" : "NL",
    "company_name" : "Onegini",
    "attentation" : "John Doe",
    "primary" : true
  } ],
  "custom_attributes" : [ {
    "name" : "myCRM",
    "value" : "ABC123456"
  } ],
  "preferred_locale" : "en_US"
}

Example HTTP response

Response 201
{
  "reference_id" : "08f831ab-a22f-4159-a851-15eec46c3717"
}
Response 400
{
  "Missing field" : {
    "error_code" : 1002,
    "error_message" : "One or more required fields is missing"
  },
  "Invalid email address" : {
    "error_code" : 1018,
    "error_message" : "Email address is empty or has an invalid format"
  },
  "Invalid redirect uri" : {
    "error_code" : 1050,
    "error_message" : "Redirect uri parameter is not whitelisted or invalid"
  }
}
Response 409
{
  "Response" : {
    "error_code" : 1003,
    "error_message" : "Email address already in use"
  }
}
Response 503
{
  "Response" : {
    "error_code" : 1001,
    "error_message" : "Registration via the API is currently not available"
  }
}

Create signed-up person

POST /api/persons/activated

Description

Endpoint allows to create a new signed-up user and automatically couple his identities. If person activation is enabled, the newly created person will be already activated.

Parameters

Type Name Description Schema
Header X-Onegini-Flow-Context-Params
optional
Additional flow context parameters.

Allowed format is "key1=value1;key2=value2"
string
Header X-Onegini-Persons-Partition-Id
optional
Partition id for the user to be validated, required when persons partitioning feature is enabled string
Body Body
required
The body includes JSON object that is composed from Profile, list of identities and EncryptedPassword objects as defined in the Onegini Java SDK. The mechanism to encrypt the password is described in the documentation in the Password Encryption chapter. The table below denotes the required fields Body

Body

Name Description Schema
encrypted_password
optional
Example : "object" encrypted_password
identities
optional
Example : [ "[identityitem](#identityitem)" ] < IdentityItem > array
profile
optional
Example : "[profile](#profile)" Profile

encrypted_password

Name Description Schema
encryption_parameter
required
Initialization vector used by encryption algorithm
Example : "BVLdWx//evkFUt1bH/96+Q=="
string
new_password
required
New user password [encrypted]
Example : "o/MCR6uS/RAmOse1+3ngU6gjf/+r8h4xWw=="
string
password
required
Current user password [encrypted]
Example : "o/MCR6uS/RAmOse1+3ngU6gjf/+r8h4xWw=="
string

Responses

HTTP Code Description Schema
201 Person was successfully created and signed up Person
400 Bad request ErrorResponse
404 Not found ErrorResponse
409 Conflict ErrorResponse
503 Feature not available ErrorResponse

Consumes

  • application/json

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/persons/activated
Request header
"string"
Request body
{
  "encrypted_password" : "object",
  "profile" : {
    "gender" : "M",
    "name" : {
      "first_name" : "John William",
      "last_name" : "Doe",
      "initials" : "J.W.D",
      "display_name" : "Mr John W. Doe, Msc."
    },
    "date_of_birth" : "1995-05-24",
    "email_addresses" : [ {
      "primary" : true,
      "verified" : false,
      "value" : "john.doe@onegini.com"
    } ],
    "phone_numbers" : [ {
      "primary" : true,
      "verified" : true,
      "value" : "+31 654 321 098"
    } ],
    "addresses" : [ {
      "house_number" : 9,
      "house_number_addition" : "2nd floor, 101",
      "street_name" : "Main street",
      "city" : "Woerden",
      "postal_code" : "1000 AA, 12345-6789",
      "region" : "Utrecht",
      "country_code" : "NL",
      "company_name" : "Onegini",
      "attentation" : "John Doe",
      "primary" : true
    } ],
    "custom_attributes" : [ {
      "name" : "myCRM",
      "value" : "ABC123456"
    } ],
    "preferred_locale" : "en_US"
  },
  "identities" : [ {
    "idp_type" : "kerberos",
    "external_person_id" : "12345-12345-12345-12345"
  } ]
}

Example HTTP response

Response 201
{
  "reference_id" : "08f831ab-a22f-4159-a851-15eec46c3717"
}
Response 400
{
  "Parameter missing" : {
    "error_code" : 1002,
    "error_message" : "One or more required fields is missing"
  },
  "Provided identity is already coupled" : {
    "error_code" : 1052,
    "error_message" : "Provided external person's identity is already coupled with another account"
  },
  "More than one identity provider with given type enabled" : {
    "error_code" : 1053,
    "error_message" : "More than one identity provider with given type enabled"
  },
  "Password parameter missing" : {
    "error_code" : 3001,
    "error_message" : "A required body parameter is missing to set the password"
  },
  "Invalid encryption" : {
    "error_code" : 3002,
    "error_message" : "Invalid parameter encryption"
  },
  "Digit validation failed" : {
    "error_code" : 6001,
    "error_message" : "Password policy: Digit count rule violation"
  },
  "Case validation failed" : {
    "error_code" : 6002,
    "error_message" : "Password policy: Lower case char count rule violation"
  },
  "MaxLength validation failed" : {
    "error_code" : 6003,
    "error_message" : "Password policy: Max password length rule violation"
  },
  "MinLength validation failed" : {
    "error_code" : 6004,
    "error_message" : "Password policy: Min password length rule violation"
  },
  "Char validation failed" : {
    "error_code" : 6005,
    "error_message" : "Password policy: Special char count rule violation"
  },
  "Case count validation failed" : {
    "error_code" : 6006,
    "error_message" : "Password policy: Upper case char count rule violation"
  },
  "Case breached validation failed" : {
    "error_code" : 6007,
    "error_message" : "Password policy: Breached password rule validation. Given password is found in a data Breach"
  }
}
Response 404
{
  "Parameter missing" : {
    "error_code" : 1020,
    "error_message" : "No idp can be found based on the specified type"
  }
}
Response 409
{
  "Person not found" : {
    "error_code" : 1003,
    "error_message" : "Email address already in use"
  },
  "External idp alreaady linked with another user" : {
    "error_code" : 1021,
    "error_message" : "External id already linked with given idp"
  }
}
Response 503
{
  "Feature not supported" : {
    "error_code" : 1001,
    "error_message" : "The person API used to sign up a person is currently not available"
  },
  "UnP IdP disabled" : {
    "error_code" : 3010,
    "error_message" : "Username password IdP is not enabled"
  }
}

Fetch multiple persons profiles

GET /api/persons/bulk/{person_ids}/profile

Description

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

Parameters

Type Name Description Schema
Header X-Onegini-Flow-Context-Params
optional
Additional flow context parameters.

Allowed format is "key1=value1;key2=value2"
string
Path person_ids
required
Comma delimited person_id variables string

Responses

HTTP Code Description Schema
200 Person coupled successully < Profile > array
400 Bad request ErrorResponse
404 Not found ErrorResponse
503 Feature not available ErrorResponse

Consumes

  • application/json

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/persons/bulk/string/profile
Request header
"string"

Example HTTP response

Response 200
[ {
  "gender" : "M",
  "name" : {
    "first_name" : "John William",
    "last_name" : "Doe",
    "initials" : "J.W.D",
    "display_name" : "Mr John W. Doe, Msc."
  },
  "date_of_birth" : "1995-05-24",
  "email_addresses" : [ {
    "primary" : true,
    "verified" : false,
    "value" : "john.doe@onegini.com"
  } ],
  "phone_numbers" : [ {
    "primary" : true,
    "verified" : true,
    "value" : "+31 654 321 098"
  } ],
  "addresses" : [ {
    "house_number" : 9,
    "house_number_addition" : "2nd floor, 101",
    "street_name" : "Main street",
    "city" : "Woerden",
    "postal_code" : "1000 AA, 12345-6789",
    "region" : "Utrecht",
    "country_code" : "NL",
    "company_name" : "Onegini",
    "attentation" : "John Doe",
    "primary" : true
  } ],
  "custom_attributes" : [ {
    "name" : "myCRM",
    "value" : "ABC123456"
  } ],
  "preferred_locale" : "en_US"
} ]
Response 400
{
  "Too many parameters" : {
    "error_code" : 1042,
    "error_message" : "The request query is limited to 100 persons identifiers"
  }
}
Response 404
{
  "Person not found" : {
    "error_code" : 1006,
    "error_message" : "No person can be found based on the specified identifier"
  }
}
Response 503
{
  "Feature not supported" : {
    "error_code" : 1001,
    "error_message" : "The registration API used to fetch person information is currently not available"
  }
}

Complete password reset for a person

POST /api/persons/complete-password-reset

Description

The endpoint allows to complete password reset initiated by api or manually from login page or dashboard

Parameters

Type Name Description Schema
Header X-Onegini-Flow-Context-Params
optional
Additional flow context parameters.

Allowed format is "key1=value1;key2=value2"
string
Header X-Onegini-Persons-Partition-Id
optional
Partition id for the user to be validated, required when persons partitioning feature is enabled string
Body Body
required
Password reset code is sent to the user in Password Reset email message. Code will be sent if user manually trigger password reset or when password reset is triggered by api /api/persons/{person_id}/password-reset The mechanism to encrypt the password is described in the documentation of the Password Encryption Body

Body

Name Description Schema
code
required
Example : "813938192371829731892731243645145124328901" string
encryption_parameter
required
Example : "+V7wNOIFDSYo8yhsfdhSAh9asdfDJRsqw==" string
password
required
Example : "+V7wn+NyMG7cVelxIIiJYrUkqJiNDJRsqw==" string

Responses

HTTP Code Description Schema
204 Password updated successully No Content
400 Bad request ErrorResponse
500 Feature not available ErrorResponse

Consumes

  • application/json

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/persons/complete-password-reset
Request header
"string"
Request body
{
  "code" : "813938192371829731892731243645145124328901",
  "password" : "+V7wn+NyMG7cVelxIIiJYrUkqJiNDJRsqw==",
  "encryption_parameter" : "+V7wNOIFDSYo8yhsfdhSAh9asdfDJRsqw=="
}

Example HTTP response

Response 400
{
  "Code expired" : {
    "error_code" : 1022,
    "error_message" : "Password reset code is expired"
  },
  "Parameter missing" : {
    "error_code" : 3001,
    "error_message" : "A required body parameter is missing to set the password"
  },
  "Invalid encryption" : {
    "error_code" : 3002,
    "error_message" : "Invalid parameter encryption"
  },
  "Digit validation failed" : {
    "error_code" : 6001,
    "error_message" : "Password policy: Digit count rule violation"
  },
  "Case validation failed" : {
    "error_code" : 6002,
    "error_message" : "Password policy: Lower case char count rule violation"
  },
  "MaxLength validation failed" : {
    "error_code" : 6003,
    "error_message" : "Password policy: Max password length rule violation"
  },
  "MinLength validation failed" : {
    "error_code" : 6004,
    "error_message" : "Password policy: Min password length rule violation"
  },
  "Char validation failed" : {
    "error_code" : 6005,
    "error_message" : "Password policy: Special char count rule violation"
  },
  "Case count validation failed" : {
    "error_code" : 6006,
    "error_message" : "Password policy: Upper case char count rule violation"
  },
  "Case breached validation failed" : {
    "error_code" : 6007,
    "error_message" : "Password policy: Breached password rule validation. Given password is found in a data Breach"
  }
}
Response 500
{
  "Response" : {
    "error_code" : 1024,
    "error_message" : "Password change failed due the internal application error"
  }
}

Verify if person is coupled

GET /api/persons/couple/{identityProviderType}/{externalIdpId}

Description

Checks if external identity provider id is already coupled for identity provider type

Parameters

Type Name Description Schema
Path externalIdpId
required
Person identifier in external identity provider string
Path identityProviderType
required
Identity provider type for which verification should be made string

Responses

HTTP Code Description Schema
200 Coupling for specified person and identity provider exists. CoupledPerson
404 Coupling for specified person and identity provider does not exist. ErrorResponse

Example HTTP request

Request path
/api/persons/couple/string/string

Example HTTP response

Response 200
{
  "person_id" : "12345"
}
Response 404
{
  "Coupling not found" : {
    "error_code" : 1030,
    "error_message" : "Person with given external identity provider id is not yet coupled with identity provider"
  }
}

Trigger a password reset using email address

POST /api/persons/password-reset

Parameters

Type Name Description Schema
Header X-Onegini-Flow-Context-Params
optional
Additional flow context parameters.

Allowed format is "key1=value1;key2=value2"
string
Body Body
required
The request body must contain email_address and optionally redirect_url parameter Body

Body

Name Description Schema
email_address
required
Example : "example@onegini.com" string
redirect_url
optional
Example : "http://example.com" string

Responses

HTTP Code Description Schema
204 Password reset successully triggered No Content
400 Bad request ErrorResponse
503 Feature not available ErrorResponse

Consumes

  • application/json

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/persons/password-reset
Request header
"string"
Request body
{
  "redirect_url" : "http://example.com",
  "email_address" : "example@onegini.com"
}

Example HTTP response

Response 400
{
  "Response" : {
    "error_code" : 1002,
    "error_message" : "Email address is missing in request body"
  },
  "Password reset failed" : {
    "error_code" : 1025,
    "error_message" : "Password reset failed. Data required for migration may not meet attribute contract related to idp configuration"
  }
}
Response 503
{
  "Response" : {
    "error_code" : 1001,
    "error_message" : "The support API is currently not available"
  }
}

Search for persons

GET /api/persons/search

Caution : operation.deprecated

Description

The endpoint allows to search for users by:

  • email address custom attribute
  • phone number
  • last modification date

Parameters

Type Name Description Schema Default
Header X-Onegini-Flow-Context-Params
optional
Additional flow context parameters.

Allowed format is "key1=value1;key2=value2"
string
Header X-Onegini-Persons-Partition-Id
optional
Partition id for the user to be validated, required when persons partitioning feature is enabled string
Query custom_attribute
optional
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. Parameter is required in case searching by custom attribute string
Query email_address
optional
Email or part of email address to search on. Parameter is required in case searching by email address attribute string
Query include_fields
optional
Comma delimited list of attributes that should be returned in the result. Possible values:
- reference_id
- email_addresses
string
Query last_modified
optional
Unix timestamp used to return attributes that have been changed after specified date. Parameter is required in case searching by last modification date string
Query limit
optional
Max number of items in the result integer (int32) 10
Query offset
optional
Index of the first item in the result integer (int32) 0
Query partial_match
optional
By default exact match will be used while searching, which result can contain at most 1 person.
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 johndoe@example.com or johndoe232@example.com but not me@johndoe.example.com.
This method can return multiple persons in the search result.
boolean "false"
Query phone_number
optional
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 %2. Parameter is required in case searching by phone number string (E.164)

Responses

HTTP Code Description Schema
200 Search result SearchResultSet
400 Bad request ErrorResponse

Consumes

  • application/json

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/persons/search
Request header
"string"

Example HTTP response

Response 200
{
  "resultSet" : [ {
    "gender" : "M",
    "name" : {
      "first_name" : "John William",
      "last_name" : "Doe",
      "initials" : "J.W.D",
      "display_name" : "Mr John W. Doe, Msc."
    },
    "date_of_birth" : "1995-05-24",
    "email_addresses" : [ {
      "primary" : true,
      "verified" : false,
      "value" : "john.doe@onegini.com"
    } ],
    "phone_numbers" : [ {
      "primary" : true,
      "verified" : true,
      "value" : "+31 654 321 098"
    } ],
    "addresses" : [ {
      "house_number" : 9,
      "house_number_addition" : "2nd floor, 101",
      "street_name" : "Main street",
      "city" : "Woerden",
      "postal_code" : "1000 AA, 12345-6789",
      "region" : "Utrecht",
      "country_code" : "NL",
      "company_name" : "Onegini",
      "attentation" : "John Doe",
      "primary" : true
    } ],
    "custom_attributes" : [ {
      "name" : "myCRM",
      "value" : "ABC123456"
    } ],
    "preferred_locale" : "en_US"
  } ],
  "pagination" : "object"
}
Response 400
{
  "Invalid request parameters" : {
    "error_code" : 2001,
    "error_message" : "No or too many request parameters in this request"
  },
  "Custom attribute name missing" : {
    "error_code" : 2002,
    "error_message" : "Name of the custom attribute is missing in request parameter"
  },
  "Search term missing" : {
    "error_code" : 2003,
    "error_message" : "Search term is missing in the request"
  }
}

Get a person

GET /api/persons/{person_id}

Description

Fetches person's details

Parameters

Type Name Description Schema
Header X-Onegini-Flow-Context-Params
optional
Additional flow context parameters.

Allowed format is "key1=value1;key2=value2"
string
Path person_id
required
string

Responses

HTTP Code Description Schema
200 Person details fetched successfully PersonDetails
404 Person not found ErrorResponse
503 Feature not available ErrorResponse

Consumes

  • application/json

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/persons/string
Request header
"string"

Example HTTP response

Response 200
{
  "person_id" : "08f831ab-a22f-4159-a851-15eec46c3717",
  "profile" : {
    "gender" : "M",
    "name" : {
      "first_name" : "John William",
      "last_name" : "Doe",
      "initials" : "J.W.D",
      "display_name" : "Mr John W. Doe, Msc."
    },
    "date_of_birth" : "1995-05-24",
    "email_addresses" : [ {
      "primary" : true,
      "verified" : false,
      "value" : "john.doe@onegini.com"
    } ],
    "phone_numbers" : [ {
      "primary" : true,
      "verified" : true,
      "value" : "+31 654 321 098"
    } ],
    "addresses" : [ {
      "house_number" : 9,
      "house_number_addition" : "2nd floor, 101",
      "street_name" : "Main street",
      "city" : "Woerden",
      "postal_code" : "1000 AA, 12345-6789",
      "region" : "Utrecht",
      "country_code" : "NL",
      "company_name" : "Onegini",
      "attentation" : "John Doe",
      "primary" : true
    } ],
    "custom_attributes" : [ {
      "name" : "myCRM",
      "value" : "ABC123456"
    } ],
    "preferred_locale" : "en_US"
  },
  "events" : [ {
    "event_identifier" : "08f831ab-a22f-4159-a851-15eec46c3717",
    "person_id" : "08f831ab-a22f-4159-a851-15eec46c3717",
    "occurred" : 1409145076543,
    "event_type" : "person.PersonCreatedEvent",
    "event_name" : "Person Created",
    "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" : 1409145074367,
  "status" : "ACTIVATED",
  "last_login" : 1409145074369,
  "logins" : 25,
  "identities" : [ {
    "name" : "Username & Password",
    "status" : "ACTIVATED",
    "last_login" : 1409145074367
  } ]
}
Response 404
{
  "Response" : {
    "error_code" : 1006,
    "error_message" : "No person can be found based on the specified identifier"
  }
}
Response 503
{
  "Response" : {
    "error_code" : 1001,
    "error_message" : "The registration API used to fetch person information is currently not available"
  }
}

Update a person

PUT /api/persons/{person_id}

Description

A person can be updated via its person_id

Parameters

Type Name Description Schema
Header X-Onegini-Flow-Context-Params
optional
Additional flow context parameters.

Allowed format is "key1=value1;key2=value2"
string
Header X-Onegini-Persons-Partition-Id
optional
Partition id for the user to be validated, required when persons partitioning feature is enabled string
Path person_id
required
string
Body Profile
required
The body of the request contains a profile object with the updated fields.
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)
Profile

Responses

HTTP Code Description Schema
204 Person updated successfully No Content
400 Person not found ErrorResponse
404 Person not found ErrorResponse
409 Email address conflict ErrorResponse
503 Feature not available ErrorResponse

Consumes

  • application/json

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/persons/string
Request header
"string"
Request body
{
  "gender" : "M",
  "name" : {
    "first_name" : "John William",
    "last_name" : "Doe",
    "initials" : "J.W.D",
    "display_name" : "Mr John W. Doe, Msc."
  },
  "date_of_birth" : "1995-05-24",
  "email_addresses" : [ {
    "primary" : true,
    "verified" : false,
    "value" : "john.doe@onegini.com"
  } ],
  "phone_numbers" : [ {
    "primary" : true,
    "verified" : true,
    "value" : "+31 654 321 098"
  } ],
  "addresses" : [ {
    "house_number" : 9,
    "house_number_addition" : "2nd floor, 101",
    "street_name" : "Main street",
    "city" : "Woerden",
    "postal_code" : "1000 AA, 12345-6789",
    "region" : "Utrecht",
    "country_code" : "NL",
    "company_name" : "Onegini",
    "attentation" : "John Doe",
    "primary" : true
  } ],
  "custom_attributes" : [ {
    "name" : "myCRM",
    "value" : "ABC123456"
  } ],
  "preferred_locale" : "en_US"
}

Example HTTP response

Response 400
{
  "Required field missing" : {
    "error_code" : 1002,
    "error_message" : "One or more required fields is missing"
  },
  "Custom attribute too long" : {
    "error_code" : 1043,
    "error_message" : "Custom attribute's key or value has exceeded max length"
  }
}
Response 404
{
  "Response" : {
    "error_code" : 1006,
    "error_message" : "No person can be found based on the specified identifier"
  }
}
Response 409
{
  "Response" : {
    "error_code" : 1003,
    "error_message" : "Email address already in use"
  }
}
Response 503
{
  "Response" : {
    "error_code" : 1001,
    "error_message" : "The registration API used to update person information is currently not available"
  }
}

Delete a person

DELETE /api/persons/{person_id}

Description

A person can be deleted via its person_id

Parameters

Type Name Description Schema
Header X-Onegini-Flow-Context-Params
optional
Additional flow context parameters.

Allowed format is "key1=value1;key2=value2"
string
Header X-Onegini-Persons-Partition-Id
optional
Partition id for the user to be validated, required when persons partitioning feature is enabled string
Path person_id
required
string
Body Reason
optional
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

Responses

HTTP Code Description Schema
204 Person deleted successfully ErrorResponse
404 Person not found ErrorResponse
503 Feature not available ErrorResponse

Consumes

  • application/json

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/persons/string
Request header
"string"
Request body
{
  "reason" : "Reason why person is blocked / deleted"
}

Example HTTP response

Response 204
{
  "error_code" : 1001,
  "error_message" : "Requested feature is currently not available"
}
Response 404
{
  "Response" : {
    "error_code" : 1006,
    "error_message" : "No person can be found based on the specified identifier"
  }
}
Response 503
{
  "Response" : {
    "error_code" : 1001,
    "error_message" : "The registration API used to delete a person is currently not available"
  }
}

Activate person account using code

POST /api/persons/{person_id}/activate/code

Description

Activate a person's account using an externally delivered code. Additional information available in topic guide.

Parameters

Type Name Description Schema
Path person_id
required
string
Body body
required
The body contains an activation code that can be used to activate a person's profile ActivatePersonRequest

Responses

HTTP Code Description Schema
200 Successful response No Content
400 Failed response No Content
503 Feature disabled No Content

Produces

  • application/json

Example HTTP request

Request path
/api/persons/string/activate/code
Request body
{
  "activation_code" : "string"
}

Example HTTP response

Response 400
{
  "Missing field" : {
    "error_code" : 1002,
    "error_message" : "One or more required fields is missing"
  },
  "Person not found" : {
    "error_code" : 1006,
    "error_message" : "No person can be found based on the specified identifier"
  },
  "Person already activated" : {
    "error_code" : 1045,
    "error_message" : "Unable to activate person as it is in wrong state"
  },
  "Person is blocked" : {
    "error_code" : 1009,
    "error_message" : "Person is blocked"
  },
  "Invalid activation code value" : {
    "error_code" : 1038,
    "error_message" : "Invalid activation code value"
  }
}

Activate person account using email

POST /api/persons/{person_id}/activate/email

Description

Activate a person's account using an token send by email. Additional information available in topic guide.

Parameters

Type Name Description Schema
Path person_id
required
Identifier of a person for which account should be activated. string
Body body
required
The body contains an activation code that can be used to activate person's profile ActivatePersonRequest

Responses

HTTP Code Description Schema
200 Successful response No Content
400 Failed response No Content
503 Feature disabled No Content

Produces

  • application/json

Example HTTP request

Request path
/api/persons/string/activate/email
Request body
{
  "activation_code" : "string"
}

Example HTTP response

Response 400
{
  "Missing field" : {
    "error_code" : 1002,
    "error_message" : "One or more required fields is missing"
  },
  "Person not found" : {
    "error_code" : 1006,
    "error_message" : "No person can be found based on the specified identifier"
  },
  "Person already activated" : {
    "error_code" : 1045,
    "error_message" : "Person already activated"
  },
  "Person is blocked" : {
    "error_code" : 1009,
    "error_message" : "Person is blocked"
  },
  "Invalid activation code value" : {
    "error_code" : 1038,
    "error_message" : "Invalid activation code value"
  }
}

Block a person

POST /api/persons/{person_id}/block

Parameters

Type Name Description Schema
Header X-Onegini-Flow-Context-Params
optional
Additional flow context parameters.

Allowed format is "key1=value1;key2=value2"
string
Path person_id
required
string
Body Reason
optional
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

Responses

HTTP Code Description Schema
204 Person blocked successully No Content
404 Not found ErrorResponse
409 Person already blocked ErrorResponse
503 Feature not available ErrorResponse

Consumes

  • application/json

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/persons/string/block
Request header
"string"
Request body
{
  "reason" : "Reason why person is blocked / deleted"
}

Example HTTP response

Response 404
{
  "Response" : {
    "error_code" : 1006,
    "error_message" : "No person can be found based on the specified identifier"
  }
}
Response 409
{
  "Response" : {
    "error_code" : 1014,
    "error_message" : "Person is already blocked"
  }
}
Response 503
{
  "Response" : {
    "error_code" : 1001,
    "error_message" : "The registration API used to block a person is currently not available"
  }
}

Couple account with External IDP

POST /api/persons/{person_id}/couple

Description

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

Parameters

Type Name Description Schema
Header X-Onegini-Flow-Context-Params
optional
Additional flow context parameters.

Allowed format is "key1=value1;key2=value2"
string
Path person_id
required
string
Body Body
required
Body

Body

Name Description Schema
external_person_id
required
Identifier of external IDP that should be coupled with Onegini IDP
Example : "12345-12345-12345-12345"
string
idp_type
required
Idp type that should be coupled with account. It should have one of the idp types added in admin panel (Configuration -> Identity Providers), eg. google, facebook, kerberos
Example : "kerberos"
string

Responses

HTTP Code Description Schema
201 Person coupled successully No Content
404 Not found ErrorResponse
409 Not found ErrorResponse

Consumes

  • application/json

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/persons/string/couple
Request header
"string"
Request body
{
  "idp_type" : "kerberos",
  "external_person_id" : "12345-12345-12345-12345"
}

Example HTTP response

Response 404
{
  "Person not found" : {
    "error_code" : 1006,
    "error_message" : "No person can be found based on the specified identifier"
  },
  "IdP not found" : {
    "error_code" : 1020,
    "error_message" : "  No idp can be found based on the specified type"
  }
}
Response 409
{
  "Response" : {
    "error_code" : 1021,
    "error_message" : "External id already linked with given idp"
  }
}

Set custom person attribute

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

Description

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

Parameters

Type Name Description Schema
Header X-Onegini-Flow-Context-Params
optional
Additional flow context parameters.

Allowed format is "key1=value1;key2=value2"
string
Header X-Onegini-Persons-Partition-Id
optional
Partition id for the user to be validated, required when persons partitioning feature is enabled string
Path person_id
required
string
Body CustomAttribute
required
The request has a JSON body containing a custom attribute object CustomAttribute

Responses

HTTP Code Description Schema
204 Attribute added successully No Content
400 Bad request ErrorResponse
404 Not found ErrorResponse
409 Attribute already exists ErrorResponse
503 Feature not available ErrorResponse

Consumes

  • application/json

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/persons/string/custom-attributes
Request header
"string"
Request body
{
  "name" : "myCRM",
  "value" : "ABC123456"
}

Example HTTP response

Response 400
{
  "Response" : {
    "error_code" : 1002,
    "error_message" : "On of the required parameters is missing or empty"
  }
}
Response 404
{
  "Response" : {
    "error_code" : 1006,
    "error_message" : "No person can be found based on the specified identifier"
  }
}
Response 409
{
  "Response" : {
    "error_code" : 1004,
    "error_message" : "This attribute already exists for this person"
  }
}
Response 503
{
  "Response" : {
    "error_code" : 1001,
    "error_message" : "The registration API used to add an identifier for a person is currently not available"
  }
}

Update custom person attribute (or merge with ADD)

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

Parameters

Type Name Description Schema
Header X-Onegini-Flow-Context-Params
optional
Additional flow context parameters.

Allowed format is "key1=value1;key2=value2"
string
Path person_id
required
string
Body CustomAttribute
required
The request has a JSON body containing a custom attribute object CustomAttribute

Responses

HTTP Code Description Schema
204 Attribute updated successully No Content
400 Bad request ErrorResponse
404 Not found ErrorResponse
503 Feature not available ErrorResponse

Consumes

  • application/json

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/persons/string/custom-attributes
Request header
"string"
Request body
{
  "name" : "myCRM",
  "value" : "ABC123456"
}

Example HTTP response

Response 400
{
  "Response" : {
    "error_code" : 1002,
    "error_message" : "On of the required parameters is missing or empty"
  }
}
Response 404
{
  "Response" : {
    "error_code" : 1006,
    "error_message" : "No person can be found based on the specified identifier"
  }
}
Response 503
{
  "Response" : {
    "error_code" : 1001,
    "error_message" : "The registration API used to update an identifier for a person is currently not available"
  }
}

Delete custom person attribute

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

Description

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

Parameters

Type Name Description Schema
Header X-Onegini-Flow-Context-Params
optional
Additional flow context parameters.

Allowed format is "key1=value1;key2=value2"
string
Header X-Onegini-Persons-Partition-Id
optional
Partition id for the user to be validated, required when persons partitioning feature is enabled string
Path attribute_name
required
string
Path person_id
required
string

Responses

HTTP Code Description Schema
204 Attribute deleted successully No Content
404 Not found ErrorResponse
503 Feature not available ErrorResponse

Consumes

  • application/json

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/persons/string/custom-attributes/string
Request header
"string"

Example HTTP response

Response 404
{
  "Response" : {
    "error_code" : 1006,
    "error_message" : "No person can be found based on the specified identifier"
  }
}
Response 503
{
  "Response" : {
    "error_code" : 1001,
    "error_message" : "The registration API used to delete an identifier for a person is currently not available"
  }
}

Invite a person

POST /api/persons/{person_id}/invite

Description

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

Parameters

Type Name Description Schema
Header X-Onegini-Flow-Context-Params
optional
Additional flow context parameters.

Allowed format is "key1=value1;key2=value2"
string
Path person_id
required
string

Responses

HTTP Code Description Schema
201 Person invited successully Person
404 Not found, blocked or incomplete ErrorResponse
409 Person already connected ErrorResponse
503 Feature not available ErrorResponse

Consumes

  • application/json

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/persons/string/invite
Request header
"string"

Example HTTP response

Response 201
{
  "reference_id" : "08f831ab-a22f-4159-a851-15eec46c3717"
}
Response 404
{
  "Person not found" : {
    "error_code" : 1006,
    "error_message" : "No person can be found based on the specified identifier"
  },
  "Person is blocked" : {
    "error_code" : 1009,
    "error_message" : "Person is blocked"
  },
  "Person incomplete" : {
    "error_code" : 1011,
    "error_message" : "The person is missing one or more required attributes to send an invitation"
  }
}
Response 409
{
  "Response" : {
    "error_code" : 1010,
    "error_message" : "The person already has connected identities"
  }
}
Response 503
{
  "Feature not available" : {
    "error_code" : 1001,
    "error_message" : "The registration API used to invite a person is currently not available"
  },
  "Invitation send failed" : {
    "error_code" : 1008,
    "error_message" : "Failed to send the invitation"
  }
}

Change password for person

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

Description

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

Parameters

Type Name Description Schema
Header X-Onegini-Flow-Context-Params
optional
Additional flow context parameters.

Allowed format is "key1=value1;key2=value2"
string
Path person_id
required
string
Body Body
required
The mechanism to encrypt the password is described in the documentation of the Password Encryption Body

Body

Name Description Schema
encryption_parameter
required
Initialization vector used by encryption algorithm
Example : "BVLdWx//evkFUt1bH/96+Q=="
string
new_password
required
New user password [encrypted]
Example : "o/MCR6uS/RAmOse1+3ngU6gjf/+r8h4xWw=="
string
password
required
Current user password [encrypted]
Example : "o/MCR6uS/RAmOse1+3ngU6gjf/+r8h4xWw=="
string

Responses

HTTP Code Description Schema
204 Password changed successully No Content
400 Bad request ErrorResponse
401 Unauthorized ErrorResponse
404 Not found ErrorResponse

Consumes

  • application/json

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/persons/string/password-change
Request header
"string"
Request body
{
  "password" : "o/MCR6uS/RAmOse1+3ngU6gjf/+r8h4xWw==",
  "new_password" : "o/MCR6uS/RAmOse1+3ngU6gjf/+r8h4xWw==",
  "encryption_parameter" : "BVLdWx//evkFUt1bH/96+Q=="
}

Example HTTP response

Response 400
{
  "Parameter missing" : {
    "error_code" : 3001,
    "error_message" : "A required body parameter is missing to set the password"
  },
  "Invalid encryption" : {
    "error_code" : 3002,
    "error_message" : "Invalid parameter encryption"
  },
  "Digit validation failed" : {
    "error_code" : 6001,
    "error_message" : "Password policy: Digit count rule violation"
  },
  "Case validation failed" : {
    "error_code" : 6002,
    "error_message" : "Password policy: Lower case char count rule violation"
  },
  "MaxLength validation failed" : {
    "error_code" : 6003,
    "error_message" : "Password policy: Max password length rule violation"
  },
  "MinLength validation failed" : {
    "error_code" : 6004,
    "error_message" : "Password policy: Min password length rule violation"
  },
  "Char validation failed" : {
    "error_code" : 6005,
    "error_message" : "Password policy: Special char count rule violation"
  },
  "Case count validation failed" : {
    "error_code" : 6006,
    "error_message" : "Password policy: Upper case char count rule violation"
  },
  "Case breached validation failed" : {
    "error_code" : 6007,
    "error_message" : "Password policy: Breached password rule validation. Given password is found in a data Breach"
  }
}
Response 401
{
  "Response" : {
    "error_code" : 1019,
    "error_message" : "  Incorrect current user password"
  }
}
Response 404
{
  "Person not found" : {
    "error_code" : 1006,
    "error_message" : "No person can be found based on the specified identifier"
  }
}

Trigger a password reset for a person

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

Parameters

Type Name Description Schema
Header X-Onegini-Flow-Context-Params
optional
Additional flow context parameters.

Allowed format is "key1=value1;key2=value2"
string
Header X-Onegini-Persons-Partition-Id
optional
Partition id for the user to be validated, required when persons partitioning feature is enabled string
Path person_id
required
string
Body RedirectUrl
optional
The request may contain optional JSON body. If the reset password request contains a redirect_url parameter, the user will be redirected to this URL after finishing the password reset procedure RedirectUrl

RedirectUrl

Name Description Schema
redirect_url
optional
Example : "http://example.com" string

Responses

HTTP Code Description Schema
204 Password reset successully triggered No Content
404 Not found ErrorResponse
409 Password reset not possible ErrorResponse
503 Feature not available ErrorResponse

Consumes

  • application/json

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/persons/string/password-reset
Request header
"string"
Request body
{
  "redirect_url" : "http://example.com"
}

Example HTTP response

Response 404
{
  "Response" : {
    "error_code" : 1006,
    "error_message" : "No person can be found based on the specified identifier"
  }
}
Response 409
{
  "Response" : {
    "error_code" : 1012,
    "error_message" : "This person does not have a password"
  }
}
Response 503
{
  "Response" : {
    "error_code" : 1001,
    "error_message" : "The support API is currently not available"
  }
}

Fetch person profile

GET /api/persons/{person_id}/profile

Description

Person profile can be fetched by providing person identifier

Parameters

Type Name Schema
Path person_id
required
string

Responses

HTTP Code Description Schema
200 Person coupled successully Profile
404 Not found ErrorResponse
503 Feature not available ErrorResponse

Consumes

  • application/json

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/persons/string/profile

Example HTTP response

Response 200
{
  "gender" : "M",
  "name" : {
    "first_name" : "John William",
    "last_name" : "Doe",
    "initials" : "J.W.D",
    "display_name" : "Mr John W. Doe, Msc."
  },
  "date_of_birth" : "1995-05-24",
  "email_addresses" : [ {
    "primary" : true,
    "verified" : false,
    "value" : "john.doe@onegini.com"
  } ],
  "phone_numbers" : [ {
    "primary" : true,
    "verified" : true,
    "value" : "+31 654 321 098"
  } ],
  "addresses" : [ {
    "house_number" : 9,
    "house_number_addition" : "2nd floor, 101",
    "street_name" : "Main street",
    "city" : "Woerden",
    "postal_code" : "1000 AA, 12345-6789",
    "region" : "Utrecht",
    "country_code" : "NL",
    "company_name" : "Onegini",
    "attentation" : "John Doe",
    "primary" : true
  } ],
  "custom_attributes" : [ {
    "name" : "myCRM",
    "value" : "ABC123456"
  } ],
  "preferred_locale" : "en_US"
}
Response 404
{
  "Person not found" : {
    "error_code" : 1006,
    "error_message" : "No person can be found based on the specified identifier"
  }
}
Response 503
{
  "Feature not supported" : {
    "error_code" : 1001,
    "error_message" : "The registration API used to fetch person information is currently not available"
  }
}

Reset a person

POST /api/persons/{person_id}/reset

Description

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

Parameters

Type Name Description Schema
Header X-Onegini-Flow-Context-Params
optional
Additional flow context parameters.

Allowed format is "key1=value1;key2=value2"
string
Path person_id
required
string

Responses

HTTP Code Description Schema
204 Password reset successfully No Content
404 Not found ErrorResponse
409 Conflict ErrorResponse
503 Feature not available ErrorResponse

Consumes

  • application/json

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/persons/string/reset
Request header
"string"

Example HTTP response

Response 404
{
  "No person found" : {
    "error_code" : 1006,
    "error_message" : "No person can be found based on the specified identifier"
  }
}
Response 409
{
  "Code expired" : {
    "error_code" : 1009,
    "error_message" : "The person is blocked"
  },
  "Not activated" : {
    "error_code" : 1016,
    "error_message" : "The person is not activated"
  },
  "No birthday attribute" : {
    "error_code" : 1017,
    "error_message" : "The person does not have a birthday which is required to invite the person again"
  }
}
Response 503
{
  "Response" : {
    "error_code" : 1001,
    "error_message" : "The person API used to reset a person is currently not available"
  }
}

Change password without current password verification

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

Description

Set password endpoint, requires only new password and is intended to be used for service purposes by superusers

Parameters

Type Name Description Schema
Header X-Onegini-Flow-Context-Params
optional
Additional flow context parameters.

Allowed format is "key1=value1;key2=value2"
string
Path person_id
required
string
Body Body
required
The mechanism to encrypt the password is described in the documentation of the Password Encryption Body

Body

Name Description Schema
encryption_parameter
required
Initialization vector used by encryption algorithm
Example : "BVLdWx//evkFUt1bH/96+Q=="
string
password
required
Current user password [encrypted]
Example : "o/MCR6uS/RAmOse1+3ngU6gjf/+r8h4xWw=="
string

Responses

HTTP Code Description Schema
204 Password changed successully No Content
400 Bad request ErrorResponse
404 Not found ErrorResponse

Consumes

  • application/json

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/persons/string/set-password
Request header
"string"
Request body
{
  "password" : "o/MCR6uS/RAmOse1+3ngU6gjf/+r8h4xWw==",
  "encryption_parameter" : "BVLdWx//evkFUt1bH/96+Q=="
}

Example HTTP response

Response 400
{
  "Parameter missing" : {
    "error_code" : 3001,
    "error_message" : "A required body parameter is missing to set the password"
  },
  "Invalid encryption" : {
    "error_code" : 3002,
    "error_message" : "Invalid parameter encryption"
  },
  "Digit validation failed" : {
    "error_code" : 6001,
    "error_message" : "Password policy: Digit count rule violation"
  },
  "Case validation failed" : {
    "error_code" : 6002,
    "error_message" : "Password policy: Lower case char count rule violation"
  },
  "MaxLength validation failed" : {
    "error_code" : 6003,
    "error_message" : "Password policy: Max password length rule violation"
  },
  "MinLength validation failed" : {
    "error_code" : 6004,
    "error_message" : "Password policy: Min password length rule violation"
  },
  "Char validation failed" : {
    "error_code" : 6005,
    "error_message" : "Password policy: Special char count rule violation"
  },
  "Case count validation failed" : {
    "error_code" : 6006,
    "error_message" : "Password policy: Upper case char count rule violation"
  },
  "Case breached validation failed" : {
    "error_code" : 6007,
    "error_message" : "Password policy: Breached password rule validation. Given password is found in a data Breach"
  }
}
Response 404
{
  "Person not found" : {
    "error_code" : 1006,
    "error_message" : "No person can be found based on the specified identifier"
  }
}

Sign up a person

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

Description

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. If person activation is enabled, person is not activated, activation code is generated. Password parameter is optional but only when account is already coupled with external identity.

Parameters

Type Name Description Schema
Header X-Onegini-Flow-Context-Params
optional
Additional flow context parameters.

Allowed format is "key1=value1;key2=value2"
string
Header X-Onegini-Persons-Partition-Id
optional
Partition id for the user to be validated, required when persons partitioning feature is enabled string
Path person_id
required
string
Body Body
required
The mechanism to encrypt the password is described in the documentation of the Password Encryption Body

Body

Name Description Schema
encryption_parameter
required
Example : "BVLdWx//evkFUt1bH/96+Q==" string
password
required
Unencrypted password 'P@ssword1'
Example : "o/MCR6uS/RAmOse1+3ngU6gjf/+r8h4xWw=="
string

Responses

HTTP Code Description Schema
204 Person signed-up successully No Content
400 Bad request ErrorResponse
404 Not found ErrorResponse
409 Conflict ErrorResponse
503 Feature not available ErrorResponse

Consumes

  • application/json

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/persons/string/sign-up
Request header
"string"
Request body
{
  "password" : "o/MCR6uS/RAmOse1+3ngU6gjf/+r8h4xWw==",
  "encryption_parameter" : "BVLdWx//evkFUt1bH/96+Q=="
}

Example HTTP response

Response 400
{
  "Parameter missing" : {
    "error_code" : 3001,
    "error_message" : "A required body parameter is missing to set the password"
  },
  "Invalid encryption" : {
    "error_code" : 3002,
    "error_message" : "Invalid parameter encryption"
  },
  "No password nor coupled" : {
    "error_code" : 1051,
    "error_message" : "Missing password parameter or account not coupled with external idp"
  },
  "Digit validation failed" : {
    "error_code" : 6001,
    "error_message" : "Password policy: Digit count rule violation"
  },
  "Case validation failed" : {
    "error_code" : 6002,
    "error_message" : "Password policy: Lower case char count rule violation"
  },
  "MaxLength validation failed" : {
    "error_code" : 6003,
    "error_message" : "Password policy: Max password length rule violation"
  },
  "MinLength validation failed" : {
    "error_code" : 6004,
    "error_message" : "Password policy: Min password length rule violation"
  },
  "Char validation failed" : {
    "error_code" : 6005,
    "error_message" : "Password policy: Special char count rule violation"
  },
  "Case count validation failed" : {
    "error_code" : 6006,
    "error_message" : "Password policy: Upper case char count rule violation"
  },
  "Case breached validation failed" : {
    "error_code" : 6007,
    "error_message" : "Password policy: Breached password rule validation. Given password is found in a data Breach"
  }
}
Response 404
{
  "Person not found" : {
    "error_code" : 1006,
    "error_message" : "No person can be found based on the specified identifier"
  }
}
Response 409
{
  "Code expired" : {
    "error_code" : 1009,
    "error_message" : "The person is blocked"
  },
  "Not activated" : {
    "error_code" : 1010,
    "error_message" : "The person is already activated"
  }
}
Response 503
{
  "Feature not supported" : {
    "error_code" : 1001,
    "error_message" : "The person API used to sign up a person is currently not available"
  },
  "UnP IdP disabled" : {
    "error_code" : 3010,
    "error_message" : "Username password IdP is not enabled"
  }
}

Generate new Action Token for a person

POST /api/persons/{person_id}/tokens

Description

Generate new Action Token for a person. Additional information can be found in topic guide

Parameters

Type Name Description Schema
Path person_id
required
string
Body body
required
Action Token configuration ActionTokenRequest

Responses

HTTP Code Description Schema
201 Successful response LoginTokenResponse
400 bad input parameter No Content
503 Feature disabled No Content

Produces

  • application/json

Example HTTP request

Request path
/api/persons/string/tokens
Request body
{
  "session_management_token" : "string",
  "redirect_uri" : "string",
  "actions" : [ {
    "type" : "LOGIN",
    "parameters" : "object"
  } ],
  "send_notification" : true
}

Example HTTP response

Response 201
{
  "token" : "069e435522f03f780d986a7cf25ea66b",
  "person_id" : "a10e844f-882f-4172-95c7-017217a1c738",
  "redirect_uri" : "http://idp.core:8080/login/dashboard"
}
Response 400
{
  "Required action missing" : {
    "error_code" : 1033,
    "error_message" : "Required token action is missing in request body"
  },
  "Unsupported action" : {
    "error_code" : 1034,
    "error_message" : "Unsupported action type in request body"
  },
  "Unsupported action parameter" : {
    "error_code" : 1035,
    "error_message" : "Unsupported configuration option for action in request body"
  },
  "Missing required action parameter" : {
    "error_code" : 1036,
    "error_message" : "Missing required action configuration parameter in request body"
  },
  "Session data not found" : {
    "error_code" : 1037,
    "error_message" : "Cannot find session data based on provided `session_management_token`"
  },
  "Person not found" : {
    "error_code" : 1006,
    "error_message" : "No person can be found based on the specified identifier"
  },
  "Identity Provider Invalid" : {
    "error_code" : 1056,
    "error_message" : "Identity provider does not exist or is disabled"
  }
}
Response 503
{
  "Action Token feature disabled" : {
    "error_code" : 1028,
    "error_message" : "Action Token functionality disabled"
  },
  "Token generation failed" : {
    "error_code" : 1031,
    "error_message" : "Action Token generation failed"
  }
}

Revoke all Action Tokens for a person

DELETE /api/persons/{person_id}/tokens

Description

Revoke all Actions tokens for a person

Parameters

Type Name Schema
Path person_id
required
string

Responses

HTTP Code Description Schema
200 Successful response No Content
400 bad input parameter No Content
503 Feature disabled No Content

Produces

  • application/json

Example HTTP request

Request path
/api/persons/string/tokens

Example HTTP response

Response 400
{
  "Person not found" : {
    "error_code" : 1006,
    "error_message" : "No person can be found based on the specified identifier"
  }
}

Generate new Action token for a person

POST /api/persons/{person_id}/tokens/login

Caution : operation.deprecated

Description

Generate new Action token for a person

Parameters

Type Name Description Schema
Path person_id
required
Identifier of a person for which token should be generated string
Body body
optional
Create Action token request details LoginTokenRequest

Responses

HTTP Code Description Schema
201 Successful response ActionTokenResponse
400 bad input parameter No Content
503 Feature disabled No Content

Produces

  • application/json

Example HTTP request

Request path
/api/persons/string/tokens/login
Request body
{ }

Example HTTP response

Response 201
{
  "token" : "069e435522f03f780d986a7cf25ea66b",
  "expire_at" : 1409145074369,
  "person_id" : "2091f05b-2177-3ec8-8e1b-fdddbd5dc523"
}
Response 400
{
  "Missing field" : {
    "error_code" : 1002,
    "error_message" : "One or more required fields is missing"
  },
  "Person not found" : {
    "error_code" : 1006,
    "error_message" : "No person can be found based on the specified identifier"
  }
}

Unblock a person

POST /api/persons/{person_id}/unblock

Parameters

Type Name Description Schema
Header X-Onegini-Flow-Context-Params
optional
Additional flow context parameters.

Allowed format is "key1=value1;key2=value2"
string
Path person_id
required
string

Responses

HTTP Code Description Schema
204 Person unblocked successully No Content
404 Not found ErrorResponse
409 Person not blocked ErrorResponse
503 Feature not available ErrorResponse

Consumes

  • application/json

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/persons/string/unblock
Request header
"string"

Example HTTP response

Response 404
{
  "Response" : {
    "error_code" : 1006,
    "error_message" : "No person can be found based on the specified identifier"
  }
}
Response 409
{
  "Response" : {
    "error_code" : 1015,
    "error_message" : "Person is not blocked"
  }
}
Response 503
{
  "Response" : {
    "error_code" : 1001,
    "error_message" : "The registration API used to unblock a person is currently not available"
  }
}

Search for persons v1

GET /api/v1/persons/search-profile

Caution : operation.deprecated

Description

The endpoint allows to search for users by:

  • email address custom attribute
  • phone number
  • last modification date

Parameters

Type Name Description Schema Default
Header X-Onegini-Flow-Context-Params
optional
Additional flow context parameters.

Allowed format is "key1=value1;key2=value2"
string
Header X-Onegini-Persons-Partition-Id
optional
Partition id for the user to be validated, required when persons partitioning feature is enabled string
Query custom_attribute
optional
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. Parameter is required in case searching by custom attribute string
Query email_address
optional
Email or part of email address to search on. Parameter is required in case searching by email address attribute string
Query include_fields
optional
Comma delimited list of attributes that should be returned in the result. Possible values:
- reference_id
- email_addresses
string
Query last_modified
optional
Unix timestamp used to return attributes that have been changed after specified date. Parameter is required in case searching by last modification date string
Query limit
optional
Max number of items in the result integer (int32) 10
Query offset
optional
Index of the first item in the result integer (int32) 0
Query partial_match
optional
By default exact match will be used while searching, which result can contain at most 1 person.
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 johndoe@example.com or johndoe232@example.com but not me@johndoe.example.com.
This method can return multiple persons in the search result.
boolean "false"
Query phone_number
optional
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 %2. Parameter is required in case searching by phone number string (E.164)

Responses

HTTP Code Description Schema
200 Search result SearchResultSet
400 Bad request ErrorResponse

Consumes

  • application/json

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/v1/persons/search-profile
Request header
"string"

Example HTTP response

Response 200
{
  "resultSet" : [ {
    "gender" : "M",
    "name" : {
      "first_name" : "John William",
      "last_name" : "Doe",
      "initials" : "J.W.D",
      "display_name" : "Mr John W. Doe, Msc."
    },
    "date_of_birth" : "1995-05-24",
    "email_addresses" : [ {
      "primary" : true,
      "verified" : false,
      "value" : "john.doe@onegini.com"
    } ],
    "phone_numbers" : [ {
      "primary" : true,
      "verified" : true,
      "value" : "+31 654 321 098"
    } ],
    "addresses" : [ {
      "house_number" : 9,
      "house_number_addition" : "2nd floor, 101",
      "street_name" : "Main street",
      "city" : "Woerden",
      "postal_code" : "1000 AA, 12345-6789",
      "region" : "Utrecht",
      "country_code" : "NL",
      "company_name" : "Onegini",
      "attentation" : "John Doe",
      "primary" : true
    } ],
    "custom_attributes" : [ {
      "name" : "myCRM",
      "value" : "ABC123456"
    } ],
    "preferred_locale" : "en_US"
  } ],
  "pagination" : "object"
}
Response 400
{
  "Invalid request parameters" : {
    "error_code" : 2001,
    "error_message" : "No or too many request parameters in this request"
  },
  "Custom attribute name missing" : {
    "error_code" : 2002,
    "error_message" : "Name of the custom attribute is missing in request parameter"
  },
  "Search term missing" : {
    "error_code" : 2003,
    "error_message" : "Search term is missing in the request"
  }
}

Search for persons v2

GET /api/v2/persons/search

Description

The endpoint allows to search for users by:

  • email address custom attribute
  • phone number
  • last modification date

Parameters

Type Name Description Schema Default
Header X-Onegini-Flow-Context-Params
optional
Additional flow context parameters.

Allowed format is "key1=value1;key2=value2"
string
Query custom_attribute
optional
Custom attribute of person to search. This should be passed as name:value pair. Example custom_attribute=attr_name:searched_value. This param can be used multiple times to pass list of criterion. This parameter is required if other search terms are not present in the query string
Query email
optional
Email address of person to search. Parameter is required in case of searching by email/username. This param can be used multiple times to pass list of criterion. This parameter is required if other search terms are not present in the query string
Query last_modified
optional
Unix timestamp used to return attributes that have been changed after specified date. Parameter is required in case searching by last modification date string
Query limit
optional
Max number of items in the result integer (int32)
Query offset
optional
Index of the first item in the result integer (int32)
Query order_by
optional
Use this parameter to receive search results sorted by given field. Allowed values are email, phone_number, last_modified. By default last_modified is applied string
Query partial_match
optional
By default exact match will be used while searching, switching this parameter to true will perform 'LIKE' searches for the given parameters. Please note that this may affect performance of your search boolean "false"
Query phone_number
optional
Phone number of person to search. If partial search is not enabled, phone number must be normalized according to E.164 standard, meaning it must not contain spaces, dashes and any other additional characters, must contain country code and must start with + sign decoded for URL into %2. Parameter is required in case searching by phone number. This param can be used multiple times to pass list of criterion. This parameter is required if other search terms are not present in the query string (E.164)

Responses

HTTP Code Description Schema
200 Person search successully triggered SearchResultSetPersonDetails
400 Bad request ErrorResponse

Consumes

  • application/json

Security

Type Name
basic basic_auth

Example HTTP request

Request path
/api/v2/persons/search
Request header
"string"

Example HTTP response

Response 200
{
  "resultSet" : [ {
    "person_id" : "08f831ab-a22f-4159-a851-15eec46c3717",
    "profile" : {
      "gender" : "M",
      "name" : {
        "first_name" : "John William",
        "last_name" : "Doe",
        "initials" : "J.W.D",
        "display_name" : "Mr John W. Doe, Msc."
      },
      "date_of_birth" : "1995-05-24",
      "email_addresses" : [ {
        "primary" : true,
        "verified" : false,
        "value" : "john.doe@onegini.com"
      } ],
      "phone_numbers" : [ {
        "primary" : true,
        "verified" : true,
        "value" : "+31 654 321 098"
      } ],
      "addresses" : [ {
        "house_number" : 9,
        "house_number_addition" : "2nd floor, 101",
        "street_name" : "Main street",
        "city" : "Woerden",
        "postal_code" : "1000 AA, 12345-6789",
        "region" : "Utrecht",
        "country_code" : "NL",
        "company_name" : "Onegini",
        "attentation" : "John Doe",
        "primary" : true
      } ],
      "custom_attributes" : [ {
        "name" : "myCRM",
        "value" : "ABC123456"
      } ],
      "preferred_locale" : "en_US"
    },
    "events" : [ {
      "event_identifier" : "08f831ab-a22f-4159-a851-15eec46c3717",
      "person_id" : "08f831ab-a22f-4159-a851-15eec46c3717",
      "occurred" : 1409145076543,
      "event_type" : "person.PersonCreatedEvent",
      "event_name" : "Person Created",
      "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" : 1409145074367,
    "status" : "ACTIVATED",
    "last_login" : 1409145074369,
    "logins" : 25,
    "identities" : [ {
      "name" : "Username & Password",
      "status" : "ACTIVATED",
      "last_login" : 1409145074367
    } ]
  } ],
  "pagination" : "object"
}
Response 400
{
  "Custom attribute name missing" : {
    "error_code" : 2002,
    "error_message" : "Name of the custom attribute is missing in request parameter"
  },
  "Search term missing" : {
    "error_code" : 2003,
    "error_message" : "Search term is missing in the request"
  }
}

Definitions

ActionTokenRequest

Name Description Schema
actions
optional
Minimum LOGIN action need to be defined, other actions are optional
Example : [ "[tokenaction](#tokenaction)" ]
< TokenAction > array
redirect_uri
optional
Used to redirect user to specific uri after action token is posted to CIM
Example : "string"
string
send_notification
optional
Flag that indicates if email with generated token should be send to the user
Example : true
boolean
session_management_token
optional
Session management token. Same as we use in /api/session
Example : "string"
string

ActionTokenResponse

Name Description Schema
expire_at
optional
Example : 1409145074369 integer (int64)
person_id
optional
Person Id from IDP or reference id returned from extension if exists
Example : "2091f05b-2177-3ec8-8e1b-fdddbd5dc523"
string
token
optional
Example : "069e435522f03f780d986a7cf25ea66b" string

ActivatePersonRequest

Contains information required to activate the account.

Name Description Schema
activation_code
optional
Code used to activate the account
Example : "string"
string

Address

Name Description Schema
attentation
optional
'To attention of' field
Example : "John Doe"
string
city
optional
Name of the city
Example : "Woerden"
string
company_name
optional
Name of the company
Example : "Onegini"
string
country_code
optional
Country code
Example : "NL"
string
house_number
optional
Numeric part of the house number
Example : 9
integer
house_number_addition
optional
Any addition that further clarifies the house number
Example : "2nd floor, 101"
string
postal_code
optional
Postal code
Example : "1000 AA, 12345-6789"
string
primary
optional
Flag to indicate whether this is the primary person's address
Example : true
boolean
region
optional
Name of the region, province or state
Example : "Utrecht"
string
street_name
optional
Name of the street
Example : "Main street"
string

CoupledPerson

Name Description Schema
person_id
optional
Example : "12345" string

CustomAttribute

Name Description Schema
name
optional
Attribute name
Example : "myCRM"
string
value
optional
Attribute value
Example : "ABC123456"
string

EmailAddress

Name Description Schema
primary
optional
Flag to indicate whether this is the primary person's email address
Example : true
boolean
value
optional
Email address value
Example : "john.doe@onegini.com"
string (email)
verified
optional
An optional flag to indicate whether this email address has been verified
Example : false
boolean

ErrorResponse

Name Description Schema
error_code
optional
Example : 1001 integer (int32)
error_message
optional
Example : "Requested feature is currently not available" string

EventInfo

Name Description Schema
client_ip
optional
Example : "192.168.10.30" string (ip)
event_identifier
optional
Example : "[identifier](#identifier)" Identifier
event_name
optional
A more descriptive name that denotes what kind of event happened
Example : "Person Created"
string
event_type
optional
The type of event that happened
Example : "person.PersonCreatedEvent"
string
occurred
optional
Example : 1409145076543 integer (int64)
person_id
optional
Example : "[identifier](#identifier)" Identifier
user_agent
optional
The full user_agent header coming from the browser of the end-user
Example : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.9; rv:31.0) Gecko/20100101 Firefox/31.0"
string

Gender

The gender of the person. Possible values: M (male), F (female), U (undefined)

Type : enum (M, F, U)

Identifier

Type : string (uuid)

IdentityItem

Name Description Schema
external_person_id
optional
Identifier of external IDP that should be coupled with Onegini IDP
Example : "12345-12345-12345-12345"
string
idp_type
optional
Idp type that should be coupled with account. It should have one of the idp types added in admin panel (Configuration -> Identity Providers), eg. google, facebook, kerberos
Example : "kerberos"
string

LoginTokenRequest

Type : object

LoginTokenResponse

Name Description Schema
person_id
optional
Person's identifier that is eligible for consuming action token
Example : "a10e844f-882f-4172-95c7-017217a1c738"
string
redirect_uri
optional
Redirect uri where person will be redirected to after consuming the action token
Example : "http://idp.core:8080/login/dashboard"
string
token
optional
Action token's value
Example : "069e435522f03f780d986a7cf25ea66b"
string

Name

Name Description Schema
display_name
optional
Displayed name, e.g. Mr John W. Doe, MSc. If no displayName is specified, firstName + lastName is returned
Example : "Mr John W. Doe, Msc."
string
first_name
optional
Person first name(s)
Example : "John William"
string
initials
optional
Person initials
Example : "J.W.D"
string
last_name
optional
Person last name
Example : "Doe"
string

Person

Name Description Schema
reference_id
optional
Example : "[identifier](#identifier)" Identifier

PersonDetails

Name Description Schema
creation_date
optional
The time that this person was created. epoch from 1-1-1970
Example : 1409145074367
integer (int64)
events
optional
Example : [ "[eventinfo](#eventinfo)" ] < EventInfo > array
identities
optional
Example : [ "[personidentity](#personidentity)" ] < PersonIdentity > array
last_login
optional
The time that the user last logged in to the Onegini IDP dashboard. epoch from 1-1-1970
Example : 1409145074369
integer (int64)
logins
optional
Example : 25 integer
person_id
optional
Example : "[identifier](#identifier)" Identifier
profile
optional
Example : "[profile](#profile)" Profile
status
optional
The status of this person or identity provider. Possible values: CREATED, INVITED, ACTIVATED, BLOCKED
Example : "ACTIVATED"
enum (CREATED, INVITED, ACTIVATED, BLOCKED)

PersonIdentity

Name Description Schema
last_login
optional
Example : 1409145074367 integer (int64)
name
optional
Example : "Username & Password" string
status
optional
Example : "ACTIVATED" enum (ACTIVATED, DISABLED, BLOCKED)

PhoneNumber

Name Description Schema
primary
optional
Flag to indicate whether this is the primary person's phone number
Example : true
boolean
value
optional
Phone number value
Example : "+31 654 321 098"
string (email)
verified
optional
An optional flag to indicate whether this phone number has been verified
Example : true
boolean

Profile

Name Description Schema
addresses
optional
Collection of person's (postal) addresses, can be empty
Example : [ "[address](#address)" ]
< Address > array
custom_attributes
optional
Collection of person's custom attributes, can be empty
Example : [ "[customattribute](#customattribute)" ]
< CustomAttribute > array
date_of_birth
optional
Timezone independent representation of a birth date
Example : "1995-05-24"
string
email_addresses
required
Collection of person's email addresses. Profile must contain at least one email address attribute
Example : [ "[emailaddress](#emailaddress)" ]
< EmailAddress > array
gender
optional
Example : "[gender](#gender)" Gender
name
optional
Example : "[name](#name)" Name
phone_numbers
optional
Collection of person's phone numbers, can be empty
Example : [ "[phonenumber](#phonenumber)" ]
< PhoneNumber > array
preferred_locale
optional
Preferred locale
Example : "en_US"
string

Reason

Name Description Schema
reason
optional
Example : "Reason why person is blocked / deleted" string

SearchResultSet

Name Description Schema
pagination
optional
Example : "object" pagination
resultSet
optional
Example : [ "[profile](#profile)" ] < Profile > array

pagination

Name Description Schema
offset
optional
Example : 0 integer (int32)
pageSize
optional
Example : 0 integer (int32)
totalResults
optional
Example : 1 integer (int32)

SearchResultSetPersonDetails

Name Description Schema
pagination
optional
Example : "object" pagination
resultSet
optional
Example : [ "[persondetails](#persondetails)" ] < PersonDetails > array

pagination

Name Description Schema
offset
optional
Example : 0 integer (int32)
pageSize
optional
Example : 0 integer (int32)
totalResults
optional
Example : 1 integer (int32)

SearchUserRequestBody

Name Description Schema
email
required
Email to search
Example : "john@example.com"
string

SearchUserResponseBody

Name Description Schema
person_id
optional
Person Id from IDP or reference id returned from extension if exists
Example : "2091f05b-2177-3ec8-8e1b-fdddbd5dc523"
string
status
required
Search status for particular email
Example : "string"
enum (CREATED, AVAILABLE_FOR_MIGRATION, NOT_FOUND)

TokenAction

Name Description Schema
parameters
optional
Action configuration parameters
Example : "object"
object
type
required
Type of action
Example : "LOGIN"
enum (LOGIN, COUPLE_EXTERNAL_IDP_FROM_SESSION, COUPLE_EXTERNAL_IDP_FROM_PARAMETERS, PERSON_ACTIVATION)

Security

basic_auth

Type : basic