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" : "[email protected]"
}

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" : "[email protected]"
  } ],
  "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",
  "identity_assurance_level" : {
    "value" : 1,
    "source" : "string",
    "last_update_time" : 1409145074367,
    "idp_id" : "12345-12345-12345-12345"
  }
}

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"
  },
  "Person creation blocked" : {
    "error_code" : 1057,
    "error_message" : "Person creation interrupted"
  },
  "Illegal characters in name" : {
    "error_code" : 1073,
    "error_message" : "The person name contains illegal characters"
  },
  "Mobile number invalid" : {
    "error_code" : 1074,
    "error_message" : "The person's mobile number is not valid. Error is returned only if 'Mobile number validation for back-end services enabled' is enabled."
  }
}

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. In case activated user is created without any identity and without password, then this user can only sign in using Action Token Login feature.

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" : "[email protected]"
    } ],
    "phone_numbers" : [ {
      "primary" : true,
      "verified" : true, 
      "tag" : "MOBILE",
      "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",
    "identity_assurance_level" : {
      "value" : 1,
      "source" : "string",
      "last_update_time" : 1409145074367,
      "idp_id" : "12345-12345-12345-12345"
    }
  },
  "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"
  },
  "Person creation interrupted" : {
    "error_code" : 1057,
    "error_message" : "Person creation interrupted"
  },
  "Duplicated external identities" : {
    "error_code" : 1058,
    "error_message" : "External identities duplicated"
  },
  "Multiple login actions requested" : {
    "error_code" : 1059,
    "error_message" : "Request should contain only one login action"
  },
  "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"
  },
  "Illegal characters in name" : {
    "error_code" : 1073,
    "error_message" : "The person name contains illegal characters"
  }
}

Response 404

{
  "Parameter missing" : {
    "error_code" : 1020,
    "error_message" : "No idp can be found based on the specified information"
  }
}

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" : "[email protected]"
  } ],
  "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",
  "identity_assurance_level" : {
    "value" : 1,
    "source" : "string",
    "last_update_time" : 1409145074367,
    "idp_id" : "12345-12345-12345-12345"
  }
} ]

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"
  }
}

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 : "[email protected]"	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
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/password-reset

Request header

"string"

Request body

{
  "redirect_url" : "http://example.com",
  "email_address" : "[email protected]"
}

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 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"
  }
}

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 [email protected] or [email protected] but not [email protected]. 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" : "[email protected]"
    } ],
    "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",
    "identity_assurance_level" : {
      "value" : 1,
      "source" : "string",
      "last_update_time" : 1409145074367,
      "idp_id" : "12345-12345-12345-12345"
    }
  } ],
  "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" : "[email protected]"
    } ],
    "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",
    "identity_assurance_level" : {
      "value" : 1,
      "source" : "string",
      "last_update_time" : 1409145074367,
      "idp_id" : "12345-12345-12345-12345"
    }
  },
  "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" : [ {
    "id" : "12345-12345-12345-12345",
    "idp_id" : "12345-12345-12345-12345",
    "name" : "Username & Password",
    "status" : "ACTIVATED",
    "last_login" : 1409145074367,
    "coupling_time" : 1499115184236
  } ],
  "partitionId" : "default",
  "identity_assurance_level" : {
    "value" : 1,
    "source" : "string",
    "last_update_time" : 1409145074367,
    "idp_id" : "12345-12345-12345-12345"
  }
}

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 or phone number only the primary is updated. For custom_attributes only the attributes listed in the request will be updated. Deleting custom attributes through this endpoint is not possible. Instead, use the 'Delete custom person attribute' endpoint. The following fields can be updated: - Gender - Name - Date of Birth - Addresses - 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" : "[email protected]"
  } ],
  "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",
  "identity_assurance_level" : {
    "value" : 1,
    "source" : "string",
    "last_update_time" : 1409145074367,
    "idp_id" : "12345-12345-12345-12345"
  }
}

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"
  },
  "Cannot delete attribute" : {
    "error_code" : 1007,
    "error_message" : "Cannot delete requested attribute as tag value does not match or attribute is mandatory"
  },
  "Illegal characters in name" : {
    "error_code" : 1073,
    "error_message" : "The person name contains illegal characters"
  },
  "Mobile number invalid" : {
    "error_code" : 1074,
    "error_message" : "The person's mobile number is not valid. Error is returned only if 'Mobile number validation for back-end services enabled' is enabled."
  }
}

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"
  }
}

Gets person's actions

GET /api/persons/{person_id}/actions

Description

Gets person's actions that can be invoked

Parameters

Type	Name	Schema
Path	person_id required	string

Responses

HTTP Code	Description	Schema
200	Person actions fetched successfully	PersonActions
404	Person with given id does not exist	No Content

Produces

• application/json

Example HTTP request

Request path

/api/persons/string/actions

Example HTTP response

Response 200

{
  "available_actions" : {
    "email_verification_resend" : true
  }
}

Response 404

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

Activate a person

POST /api/persons/{person_id}/activate

Description

Activates the person to make it possible to log in. There is no coupling made yet so to give possibility to an end user to login please us login methods (qr login, mobile login, action token login) which doesn't require coupling or couple the account with any identity provider (facebook, google, etc.)

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	Identifier of a person	string

Responses

HTTP Code	Description	Schema
200	Person activated successfully	No Content
400	Person status in wrong state. Only person in CREATED state can be activated.	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/activate

Request header

"string"

Example HTTP response

Response 400

{
  "Response" : {
    "error_code" : 1061,
    "error_message" : "Person status in wrong state. Only person in CREATED state can be activated."
  }
}

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 person API is 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"
  }
}

Delete person attribute

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

Description

This endpoint can be used to nullify certain person attributes. Currently it supports the attributes 'gender' and 'date_of_birth'.

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
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/attributes/string

Request header

"string"

Example HTTP response

Response 400

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

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"
  }
}

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"
  }
}

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. The endpoint supports only one custom attribute at once. Custom attribute collection is supported by the endpoint: Update 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
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" : "One 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

Description

The endpoint supports only one custom attribute at once. Custom attribute collection is supported by the endpoint: Update 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
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" : "One 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"
  }
}

Force password change on next sign in

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

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

Responses

HTTP Code	Description	Schema
204	Force password change has been applied. User will be prompted to change the password on next sign in.	No Content
404	Not found	ErrorResponse
409	Password reset not possible	ErrorResponse
503	Feature not available	ErrorResponse

Security

Type	Name
basic	basic_auth

Example HTTP request

Request path

/api/persons/string/force-password-change

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" : 1012,
    "error_message" : "This person does not have a password"
  }
}

Response 503

{
  "Response" : {
    "error_code" : 1001,
    "error_message" : "The person API 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
Body	PersonInviteApiRequest optional	Additional invite parameters (context)	PersonInviteApiRequest

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"

Request body

{
  "additional_parameters" : {
    "param1" : "param1value",
    "param2" : "param2value"
  }
}

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" : "[email protected]"
  } ],
  "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",
  "identity_assurance_level" : {
    "value" : 1,
    "source" : "string",
    "last_update_time" : 1409145074367,
    "idp_id" : "12345-12345-12345-12345"
  }
}

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	Encrypted password. (In example 'P@ssword1' after encryption) 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" : "Feature `action token login` disabled"
  },
  "Action Token app to web feature disabled" : {
    "error_code" : 1060,
    "error_message" : "Feature `action token app to web` disabled"
  },
  "Coupling Token feature disabled" : {
    "error_code" : 1054,
    "error_message" : "Feature `action token coupling` 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 (outdated)

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

Caution : operation.deprecated

Description

Generate new Action token for a person (outdated)

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"
  }
}

Initialize attribute verification

POST /api/persons/{person_id}/verification/{channel}/init

Description

Initialize verification of an existing person's attribute for the selected channel

Parameters

Type	Name	Description	Schema
Path	channel required	either 'email' or 'mobile'	string
Path	person_id required		string

Responses

HTTP Code	Description	Schema
204	Attribute verification initialized successfully	No Content
400	Bad Request	No Content
404	Person with given id does not exist	No Content

Example HTTP request

Request path

/api/persons/string/verification/string/init

Example HTTP response

Response 400

{
  "Verification channel unknown" : {
    "error_code" : 1069,
    "error_message" : "Verification channel unknown or unsupported"
  },
  "Person channel verification unavailable" : {
    "error_code" : 1070,
    "error_message" : "Person channel not available for verification"
  },
  "Person channel already verified" : {
    "error_code" : 1076,
    "error_message" : "The person attribute verification initialization failed"
  }
}

Response 404

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

Resend verification code for user

POST /api/persons/{person_id}/verification/{channel}/resend

Description

Resend verification code for existing person via email or sms

Parameters

Type	Name	Description	Schema
Path	channel required	either 'email' or 'mobile'	string
Path	person_id required		string

Responses

HTTP Code	Description	Schema
204	Verification code send successfully	No Content
400	Bad Request	No Content
404	Person with given id does not exist	No Content

Example HTTP request

Request path

/api/persons/string/verification/string/resend

Example HTTP response

Response 400

{
  "Verification channel unknown" : {
    "error_code" : 1069,
    "error_message" : "Verification channel unknown or unsupported"
  },
  "Person channel verification unavailable" : {
    "error_code" : 1070,
    "error_message" : "Person channel not available for verification"
  },
  "Person channel already verified" : {
    "error_code" : 1071,
    "error_message" : "Attribute is already verified"
  }
}

Response 404

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

Verify user's code

POST /api/persons/{person_id}/verification/{channel}/{code}

Description

Verify existing person attribute for the selected channel

Parameters

Type	Name	Description	Schema
Path	channel required	either 'email' or 'mobile'	string
Path	code required	a code that was delivered by the selected channel	string
Path	person_id required		string

Responses

HTTP Code	Description	Schema
204	Verification code send successfully	No Content
400	Bad Request	No Content
404	Person with given id does not exist	No Content

Example HTTP request

Request path

/api/persons/string/verification/string/string

Example HTTP response

Response 400

{
  "Verification channel unknown" : {
    "error_code" : 1069,
    "error_message" : "Verification channel unknown or unsupported"
  },
  "Person channel verification unavailable" : {
    "error_code" : 1070,
    "error_message" : "Person channel not available for verification"
  },
  "Person channel already verified" : {
    "error_code" : 1076,
    "error_message" : "The person attribute verification initialization failed"
  },
  "Attriubute verification code blocked" : {
    "error_code" : 1077,
    "error_message" : "Person attribute verification code blocked"
  }
}

Response 404

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

Verify if person is coupled

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

Caution : operation.deprecated

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/v1/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"
  }
}

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 [email protected] or [email protected] but not [email protected]. 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" : "[email protected]"
    } ],
    "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",
    "identity_assurance_level" : {
      "value" : 1,
      "source" : "string",
      "last_update_time" : 1409145074367,
      "idp_id" : "12345-12345-12345-12345"
    }
  } ],
  "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"
  }
}

Couple account with External IDP V1

POST /api/v1/persons/{person_id}/couple

Caution : operation.deprecated

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. Please note that since this endpoint is marked as deprecated it will not be extended with a support for autoActivation during 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	Conflict	ErrorResponse

Consumes

• application/json

Security

Type	Name
basic	basic_auth

Example HTTP request

Request path

/api/v1/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 information"
  }
}

Response 409

{
  "Response" : {
    "error_code" : 1021,
    "error_message" : "External id already linked with given idp"
  }
}

Verify if person is coupled

GET /api/v2/persons/couple/{identityProviderId}/{externalIdpId}

Description

Checks if external identity is already coupled for identity provider id

Parameters

Type	Name	Description	Schema
Path	externalIdpId required	Person identifier in external identity provider	string
Path	identityProviderId required	Identity provider id 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/v2/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"
  }
}

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" : "[email protected]"
      } ],
      "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",
      "identity_assurance_level" : {
        "value" : 1,
        "source" : "string",
        "last_update_time" : 1409145074367,
        "idp_id" : "12345-12345-12345-12345"
      }
    },
    "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" : [ {
      "id" : "12345-12345-12345-12345",
      "idp_id" : "12345-12345-12345-12345",
      "name" : "Username & Password",
      "status" : "ACTIVATED",
      "last_login" : 1409145074367,
      "coupling_time" : 1499115184236
    } ],
    "partitionId" : "default",
    "identity_assurance_level" : {
      "value" : 1,
      "source" : "string",
      "last_update_time" : 1409145074367,
      "idp_id" : "12345-12345-12345-12345"
    }
  } ],
  "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"
  }
}

Couple account with External IDP V2

POST /api/v2/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. This endpoint support autoActivation which means that the person account will get activated automatically in case it is currently in INACTIVE state and specified external Identity Provider has autoActivation feature enabled.

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_id required	Idp id that should be coupled with account. This can be obtained using Identity Providers Config API Example : "12345-12345-12345-12345"	string

Responses

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

Consumes

• application/json

Security

Type	Name
basic	basic_auth

Example HTTP request

Request path

/api/v2/persons/string/couple

Request header

"string"

Request body

{
  "idp_id" : "12345-12345-12345-12345",
  "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 information"
  }
}

Response 409

{
  "Response" : {
    "error_code" : 1021,
    "error_message" : "External id already linked with given idp"
  }
}

Decouple account from External IDP

POST /api/v2/persons/{person_id}/decouple

Description

API allows to decouple idp account from external IDP. It requires to pass person identifier in the url and external IdP data required for decoupling

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	Person's identifier from external identity provider that should be coupled with Onegini CIM Example : "12345-12345-12345-12345"	string
idp_id required	Idp id that should be coupled with account. This can be obtained using Identity Providers Config API Example : "12345-12345-12345-12345"	string

Responses

HTTP Code	Description	Schema
204	Person decoupled 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/v2/persons/string/decouple

Request header

"string"

Request body

{
  "idp_id" : "12345-12345-12345-12345",
  "external_person_id" : "12345-12345-12345-12345"
}

Example HTTP response

Response 400

{
  "Decoupling disabled" : {
    "error_code" : 1067,
    "error_message" : "Decoupling for given identity provider is disabled"
  }
}

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 information"
  },
  "Coupling not found" : {
    "error_code" : 1061,
    "error_message" : "Provided external identity is not coupled with given person"
  }
}

Remove identity from account (decoupling V3)

DELETE /api/v3/persons/{person_id}/identities/{identity_id}

Description

API allows to remove external identity from account. It requires to pass person identifier and identity identifier in the url

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	identity_id required		string
Path	person_id required		string

Responses

HTTP Code	Description	Schema
204	Person decoupled successfully	No Content
400	Bad Request	ErrorResponse
404	Not found	ErrorResponse

Security

Type	Name
basic	basic_auth

Example HTTP request

Request path

/api/v3/persons/string/identities/string

Request header

"string"

Example HTTP response

Response 400

{
  "Decoupling disabled" : {
    "error_code" : 1067,
    "error_message" : "Decoupling for given identity provider is disabled"
  }
}

Response 404

{
  "Person not found" : {
    "error_code" : 1006,
    "error_message" : "No person can be found based on the specified identifier"
  },
  "Identity not found" : {
    "error_code" : 1072,
    "error_message" : "No identity can be found based on the specified information"
  },
  "IdP not found" : {
    "error_code" : 1020,
    "error_message" : "No idp can be found based on the specified information"
  },
  "Coupling not found" : {
    "error_code" : 1061,
    "error_message" : "Provided external identity is not coupled with given person"
  }
}

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 : "[email protected]"	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)

IdentityAssuranceLevel

The Identity Assurance Level of a user. Update person via PersonAPI can change IAL level. Provided range should be higher than the currently assigned to the user. If default value is 1 for example, than 2, 3 or 4 can be set.

Name	Description	Schema
idp_id optional	The identifier of IdP if source is LOGIN_METHOD Example : "12345-12345-12345-12345"	string
last_update_time optional	Describes when IAL value was set Example : 1409145074367	integer (int64)
source optional	Describes how IAL value was set Example : "string"	enum (DEFAULT, MANUAL, LOGIN_METHOD, IDENTITY_PROOFING)
value optional	The Identity Assurance Level (IAL) value of a person Example : 1	integer

IdentityItem

Name	Description	Schema
external_person_id optional	Person's identifier from external identity provider that should be coupled with Onegini CIM 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

PersonActions

Name	Description	Schema
available_actions required	Example : "[personavailableactions](#personavailableactions)"	PersonAvailableActions

PersonAvailableActions

Name	Description	Schema
email_verification_resend required	Indicate if email verification resend action can be performed on this person Example : true	boolean

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
identity_assurance_level optional	Example : "[identityassurancelevel](#identityassurancelevel)"	IdentityAssuranceLevel
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
partitionId optional	The partition of this person Example : "default"	string
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
coupling_time optional	Example : 1499115184236	integer (int64)
id optional	Example : "12345-12345-12345-12345"	string
idp_id optional	Example : "12345-12345-12345-12345"	string
last_login optional	Example : 1409145074367	integer (int64)
name optional	Example : "Username & Password"	string
status optional	Example : "ACTIVATED"	enum (ACTIVATED, DISABLED, BLOCKED)

PersonInviteApiRequest

Name	Description	Schema
additional_parameters required	Additional invitation parameters (context) Example : {<br> "param1" : "param1value",<br> "param2" : "param2value"<br>}	object

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
identity_assurance_level optional	Example : "[identityassurancelevel](#identityassurancelevel)"	IdentityAssuranceLevel
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 : "[email protected]"	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