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" : "john.doe@onegini.com"
    } ],
    "phone_numbers" : [ {
      "primary" : true,
      "verified" : true,
      "tag" : "mobile number",
      "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"
  }
}
Response 503
{
  "Response" : {
    "error_code" : 1001,
    "error_message" : "The credentials API is currently not available"
  }
}

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 : "foo@example.org"
string

Responses

HTTP Code Description Schema
200 Credentials validated successfully Profile
400 Bad request ErrorResponse
401 Invalid credentials or person not allowed to authenticate AuthenticateUserFailedResponse
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" : "foo@example.org",
  "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" : "john.doe@onegini.com"
  } ],
  "phone_numbers" : [ {
    "primary" : true,
    "verified" : true,
    "tag" : "mobile number",
    "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
{
  "status" : "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 blocked" : {
    "error_code" : 1009,
    "error_message" : "The person is blocked"
  },
  "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

AuthenticateUserFailedResponse

Name Description Schema
status
optional
current status of person (if available)
Example : "blocked"
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 : "john.doe@onegini.com"
string (email)
verified
optional
An optional flag to indicate whether this email address has been verified
Example : false
boolean

ErrorResponse

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

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