Credential API¶

Overview¶

This document describes the Onegini IdP API operations to validate credentials

Version information¶

Version : 1.0.0

Paths¶

Process action token¶

POST /api/credentials/token

Description¶

Execute actions linked with specific action token

Parameters¶

Type	Name	Description	Schema
Body	CredentialsTokenRequestBody required	Request parameters must include Action Token that will be validated	ActionTokenRequest

Responses¶

HTTP Code	Description	Schema
200	Action Token processed successfully	ActionTokenProcessResponse
400	Bad request	ErrorResponse
503	Feature not available	ErrorResponse

Consumes¶

application/json

Produces¶

application/json

Security¶

Type	Name
basic	basic_auth

Example HTTP request¶

Request path¶

/api/credentials/token

Request body¶

{
  "token" : "8a7sdasydage2h323bnaswz6stday2h3g1jh23vnvavwedqy"
}

Example HTTP response¶

Response 200¶

{
  "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,
      "tag" : "work email",
      "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",
    "reference_id" : "f3950090-7d75-40dd-a6b6-de3bca5f7288"
  },
  "results" : [ {
    "type" : "LOGIN",
    "parameters" : {
      "idp_id" : "123-123-123",
      "external_id" : "432-432-432"
    },
    "execution_status" : "SUCCESS"
  } ],
  "redirect_uri" : "https://redirect/"
}

Response 400¶

{
  "Action token not found" : {
    "error_code" : 3011,
    "error_message" : "Invalid token"
  },
  "One or more actions have failed" : {
    "error_code" : 3012,
    "error_message" : "One or more actions have failed",
    "details" : [ {
      "failed_actions" : [ "COUPLE_IDENTITY" ]
    } ]
  },
  "Person is blocked" : {
    "error_code" : 1009,
    "error_message" : "Person is blocked"
  },
  "External identity already coupled" : {
    "error_code" : 1052,
    "error_message" : "Provided external person's identity is already coupled with another account"
  },
  "Identity Provider Invalid" : {
    "error_code" : 1056,
    "error_message" : "Identity provider does not exist or is disabled"
  },
  "Person in invalid state" : {
    "error_code" : 1063,
    "error_message" : "Unable to login person as it is in wrong state"
  }
}

Response 503¶

{
  "Response" : {
    "error_code" : 1001,
    "error_message" : "The credentials API is currently not available"
  },
  "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"
  }
}

Validate action token¶

POST /api/credentials/tokens/validate

Caution : operation.deprecated

Description¶

The endpoint allows to validate action token.
Deprecated since 6.0.0-M11, will be removed in next major release. Please use /api/credentials/token instead.

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	Request parameters must include Action Token that will be validated	Body

Body

Name	Description	Schema
token required	Action Token to validate Example : `"8a7sdasydage2h323bnaswz6stday2h3g1jh23vnvavwedqy"`	string

Responses¶

HTTP Code	Description	Schema
204	Action Token validated successfully	No Content
400	Bad request	ErrorResponse
401	Validation failed	ErrorResponse
503	Feature not available	ErrorResponse

Consumes¶

application/json

Produces¶

application/json

Security¶

Type	Name
basic	basic_auth

Example HTTP request¶

Request path¶

/api/credentials/tokens/validate

Request header¶

"string"

Request body¶

{
  "token" : "8a7sdasydage2h323bnaswz6stday2h3g1jh23vnvavwedqy"
}

Example HTTP response¶

Response 400¶

{
  "Missing parameter" : {
    "error_code" : 3001,
    "error_message" : "Missing required request parameter"
  },
  "Feature action token login disabled" : {
    "error_code" : 1028,
    "error_message" : "Feature `action token login` disabled"
  }
}

Response 401¶

{
  "Invalid Token" : {
    "error_code" : 3011,
    "error_message" : "Invalid Action Token"
  }
}

Response 503¶

{
  "Response" : {
    "error_code" : 1001,
    "error_message" : "The credentials API is currently not available"
  }
}

Validate person credentials¶

POST /api/credentials/validate

Description¶

The endpoint allows to validate person credentials.

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	Request parameters must include username, encrypted password and encryption parameter to ensure the encryption security	Body

Body

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

Responses¶

HTTP Code	Description	Schema
200	Credentials validated successfully	Profile
400	Bad request	ErrorResponse
401	User is unauthorized. Additional error code pointing the reason is returned in the error_code field	ErrorResponse
403	Unauthorized	ErrorResponse
503	Feature not available	ErrorResponse

Consumes¶

application/json

Produces¶

application/json

Security¶

Type	Name
basic	basic_auth

Example HTTP request¶

Request path¶

/api/credentials/validate

Request header¶

"string"

Request body¶

{
  "username" : "[email protected]",
  "password" : "o/MCR6uS/RAmOse1+3ngU6gjf/+r8h4xWw==",
  "encryption_parameter" : "BVLdWx//evkFUt1bH/96+Q=="
}

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,
    "tag" : "work email",
    "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",
  "reference_id" : "f3950090-7d75-40dd-a6b6-de3bca5f7288"
}

Response 400¶

{
  "Missing parameter" : {
    "error_code" : 3001,
    "error_message" : "Missing required request parameter"
  },
  "Invalid encryption parameter" : {
    "error_code" : 3002,
    "error_message" : "Invalid parameter encryption"
  }
}

Response 401¶

{
  "invalid_credentials" : {
    "error_code" : 3013,
    "error_message" : "You entered invalid credentials. Try again or contact support.",
    "details" : [ {
      "code" : "invalid_credentials",
      "error_message_key" : "my.message.key.user_blocked"
    } ]
  },
  "Person blocked" : {
    "error_code" : 1009,
    "error_message" : "The person is blocked"
  },
  "Person's UnP Identity blocked" : {
    "error_code" : 1068,
    "error_message" : "Person's UnP Identity is blocked"
  }
}

Response 403¶

{
  "Attributes verification failed" : {
    "error_code" : 3003,
    "error_message" : "Person found but is missing one or more verified attributes which are required"
  },
  "Person inactive" : {
    "error_code" : 1039,
    "error_message" : "Person is inactive"
  }
}

Response 503¶

{
  "Response" : {
    "error_code" : 1001,
    "error_message" : "The credentials API is currently not available"
  }
}

Definitions¶

ActionTokenProcessResponse¶

Name	Description	Schema
profile optional	Profile for which action token has been processed. Example : `"[profile](#profile)"`	Profile
redirect_uri optional	Url to redirect user to after processing all actions. Example : `"https://redirect/"`	string
results optional	List of processed actions with it's results. Example : `[ "[tokenactionresult](#tokenactionresult)" ]`	< TokenActionResult > array

ActionTokenRequest¶

Name	Description	Schema
token required	Action Token to process Example : `"8a7sdasydage2h323bnaswz6stday2h3g1jh23vnvavwedqy"`	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

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
tag optional	An optional tag to indicate the difference (eg. private email, work email) Example : `"work email"`	string
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
details optional	Example : `"Additional information attached to the error response"`	string
error_code optional	Example : `1001`	integer (int32)
error_message optional	Example : `"Requested feature is currently not available"`	string

Gender¶

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

Type : enum (M, F, U)

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

PhoneNumber¶

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

Profile¶

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

TokenActionResult¶

Result of processed action

Name	Description	Schema
execution_status optional	Example : `"SUCCESS"`	enum (SUCCESS, FAILURE)
parameters optional	Action configuration parameters Example : `{<br> "idp_id" : "123-123-123",<br> "external_id" : "432-432-432"<br>}`	object
type required	Action type Example : `"LOGIN"`	enum (LOGIN, COUPLE_EXTERNAL_IDP_FROM_SESSION, COUPLE_EXTERNAL_IDP_FROM_PARAMETERS, PERSON_ACTIVATION)

Security¶

basic_auth¶

Type : basic