Api documentation

Learn how to get started with our Api documentation

Documentation

API Reference - IdentityAPI 1 Json Yaml Try

Identity API manages online identity and credentials of users. This covers signup process, confirmations of contact points, changing and recovery of forgotten passwords and usernames. Logins from external identity providers can be linked to user profile. Hint pictures, security questions and password policy enhance user experience and security of the recovery processes.

Working with credentials

Gets security questions

GET /v1/identity/users/{username}/questions

Gets the security questions which user has selected to be used for identification and password change in case of forgotten password.

Parameter Type/Format Description
username
required

Path / String

The username. Username is unique identifier

Response

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [error handling](common-getstarted.html#error-handling)

200 - OK 

{
  "questions": [
    {
      "question-id": "string",
      "question": "string",
      "description": "string",
      "answer-format-type": "string",
      "answer-format": "string",
      "available-answers": [
        {
          "value": "string",
          "text": "string"
        }
      ]
    }
  ]
}

Validate answers on security questions

POST /v1/identity/users/{username}/answers/validate

Parameter Type/Format Description
req
required

Body /

Security answer validation request

username
required

Path / String

The username. Username is unique identifier

Response

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [error handling](common-getstarted.html#error-handling)

440 - Your request was well constructed but it could not be processed. Consider the following possible problems and look into response for more details: | Problem | Description | |-|-| | [answers-not-valid]() | Supplied answers to security questions are not valid |

200 - OK - Answers are valid

Set profile picture for specific user

PUT /v1/identity/users/{username}/profile-picture

Sets the profile picture for specific user

Parameter Type/Format Description
username
required

Path / String

The username. Username is unique identifier

cmd
required

Body /

Command with parameters to set profile picture

Response

204 - No content

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [error handling](common-getstarted.html#error-handling)

Add linked login for authenticated user

POST /v1/identity/me/logins

Use to link login from external identity provider to user profile. Provider must support OAuth2 and OpenID Connect.

Parameter Type/Format Description
cmd
required

Body /

Command with parameters to register linked login

Response

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [error handling](common-getstarted.html#error-handling)

440 - Your request was well constructed but it could not be processed. Consider the following possible problems and look into response for more details: | Problem | Description | |-|-| | [login-already-used]() | Login {login} at {provider} is already linked to another user profile | | [provider-not-supported]() | Provider {provider} not supported |

204 - No content - Linked login added to user profile

Remove linked login for authenticated user

DELETE /v1/identity/me/logins/{login}

Parameter Type/Format Description
login
required

Path / String

Login at external identity provider such as facebook username or gmail address

Response

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [error handling](common-getstarted.html#error-handling)

204 - No content - Linked login removed

Set new password for authenticated user

PUT /v1/identity/me/password

Parameter Type/Format Description
cmd
required

Body /

Command with parameters to change password

Response

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [error handling](common-getstarted.html#error-handling)

440 - Your request was well constructed but it could not be processed. Consider the following possible problems and look into response for more details: | Problem | Description | |-|-| | [password-same-as-existing]() | New password cannot be same as existing password | | [password-does-not-meet-requirements]() | Password is weaker than allowed by password strength policy|

204 - No content - Password changed

Change username for authenticated user

PUT /v1/identity/me/username

Sets new username for authenticated user. Username cannot be in use by other user

Parameter Type/Format Description
cmd
required

Body /

Command contains parameters for change of username.

Response

440 - Your request was well constructed but it could not be processed. Consider the following possible problems and look into response for more details: | Problem | Description | |-|-| | [username-already-used]() | Username {username} is already used |

204 - No content - Username changed

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [error handling](common-getstarted.html#error-handling)

Set answers to security questions for authenticated user

PUT /v1/identity/me/answers

Sets answers for questeions which user has selected to be used for authentication in case of forgotten username or password

Parameter Type/Format Description
cmd
required

Body /

Command with parameters to set security answers

Response

200 - OK

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [error handling](common-getstarted.html#error-handling) 

{
  "questions": [
    {
      "question-id": "string",
      "question": "string",
      "description": "string",
      "answer-format-type": "string",
      "answer-format": "string",
      "available-answers": [
        {
          "value": "string",
          "text": "string"
        }
      ]
    }
  ]
}

Reset password for user

POST /v1/identity/users/{username}/password/reset

Resets user password by randomly generating new one and initiates password reset process

Parameter Type/Format Description
username
required

Path / String

The username. Username is unique identifier

cmd
required

Body /

Command with parameters for password reset

Response

204 - No content - Password reset process initiated

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [error handling](common-getstarted.html#error-handling)

Recover forgotten username for specific user

POST /v1/identity/users/{username}/username-recovery

Initiates process to recover forgotten username

Parameter Type/Format Description
username
required

Path / String

The username. Username is unique identifier

cmd
required

Body /

Command with parameters to recover forgotten username

Response

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [error handling](common-getstarted.html#error-handling)

202 - Accepted - Username recovery initiated

Check if username is available

GET /v1/identity/users/{username}/available

Parameter Type/Format Description
username
required

Path / String

The username. Username is unique identifier

Response

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [error handling](common-getstarted.html#error-handling)

410 - Gone - Username is not available

200 - OK - Username is available

Set hint picture for specific user

PUT /v1/identity/users/{username}/hint-picture

Sets the hint picture for specific user

Parameter Type/Format Description
username
required

Path / String

The username. Username is unique identifier

cmd
required

Body /

Command with parameters to set hint picture

Response

204 - No content

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [error handling](common-getstarted.html#error-handling)

Working with users

Get profile of authenticated user

GET /v1/identity/me

Provides user profile of authenticated user

Parameter Type/Format Description
include
optional

Query / Array

List of fields to include in response. For more information see general guidance on [response shaping](common-getstarted.html#shaping)

trim
optional

Query / Array

List of fields to trim from response. For more information see general guidance on [response shaping](common-getstarted.html#shaping)

Response

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [error handling](common-getstarted.html#error-handling)

200 - OK 

{
  "user-id": "string",
  "username": "string",
  "customer-number": "string",
  "last-login": "string",
  "last-answer-validated": "string",
  "last-password-reset": "string",
  "lock-expires": "string",
  "first-name": "string",
  "last-name": "string",
  "email": "string",
  "email-verified": "boolean",
  "phone-number": "string",
  "phone-number-verified": "boolean",
  "hint-picture-url": "string",
  "profile-picture-url": "string",
  "linked-logins": [
    {
      "login": "string",
      "provider": "string"
    }
  ],
  "multifactor-enabled": "boolean",
  "status": "string"
}

Register new email address

PUT /v1/identity/me/email

Sets new or changes existing email in user profile and initates email verification process. Email cannot be in use by other user. Unverified email will be removed after period set by policy.

Parameter Type/Format Description
cmd
required

Body /

Command with parameters for new email

Response

202 - Accepted - Email verification kicked off

440 - Your request was well constructed but it could not be processed. Consider the following possible problems and look into response for more details: | Problem | Description | |-|-| | [email-already-used]() | Email address {email} is already used |

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [error handling](common-getstarted.html#error-handling)

Confirm new email address for authenticated user

PUT /v1/identity/me/email/confirm

Confirms users control of new email address based on OTP that was sent over email. This completes email verification process.

Parameter Type/Format Description
cmd
required

Body /

Command with parameters to confirm email address

Response

204 - No content - Email confirmed

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [error handling](common-getstarted.html#error-handling)

440 - Your request was well constructed but it could not be processed. Consider the following possible problems and look into response for more details: | Problem | Description | |-|-| | [verification-expired]() | Time allowed for verfication has expired |

Register new phone number for authenticated user

PUT /v1/identity/me/phone-number

Sets new or changes exising phone number in user profile and initiates phone number verification process. Phone number cannot be in use by other user. Unverified phone numbers will be removed after period set by policy.

Parameter Type/Format Description
cmd
required

Body /

Command with parameters for changing phone number

Response

440 - Your request was well constructed but it could not be processed. Consider the following possible problems and look into response for more details: | Problem | Description | |-|-| | [phone-number-already-used]() | Phone number {phone} is already used |

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [error handling](common-getstarted.html#error-handling)

202 - Accepted - Phone number verification initiated

Confirm new phone number for authenticated user

PUT /v1/identity/me/phone-number/confirm

Confirms users control of new phone number based on OTP sent over SMS

Parameter Type/Format Description
cmd
required

Body /

Command with parameters to confirm phone number

Response

204 - No content - Phone number confirmed

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [error handling](common-getstarted.html#error-handling)

440 - Your request was well constructed but it could not be processed. Consider the following possible problems and look into response for more details: | Problem | Description | |-|-| | [verification-expired]() | Time allowed for verfication has expired |

Find user

GET /v1/identity/users

Finds user profile matching email, linked login, phone or customer number. All supplied parameters are matched against user repository. Parameters are optional but at least one parameter must be supplied. If more than one user profile matches supplied criteria `404 Not found` will be returned.

Parameter Type/Format Description
customer
optional

Query / String

The username. Username is unique identifier

email
optional

Query / String

The username. Username is unique identifier

include
optional

Query / Array

List of fields to include in response. For more information see general guidance on [response shaping](common-getstarted.html#shaping)

login
optional

Query / String

The username. Username is unique identifier

phone-number
optional

Query / String

The username. Username is unique identifier

trim
optional

Query / Array

List of fields to trim from response. For more information see general guidance on [response shaping](common-getstarted.html#shaping)

Response

200 - OK

404 - Not found or multiple matches

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [error handling](common-getstarted.html#error-handling) 

{
  "user-id": "string",
  "username": "string",
  "customer-number": "string",
  "last-login": "string",
  "last-answer-validated": "string",
  "last-password-reset": "string",
  "lock-expires": "string",
  "first-name": "string",
  "last-name": "string",
  "email": "string",
  "email-verified": "boolean",
  "phone-number": "string",
  "phone-number-verified": "boolean",
  "hint-picture-url": "string",
  "profile-picture-url": "string",
  "linked-logins": [
    {
      "login": "string",
      "provider": "string"
    }
  ],
  "multifactor-enabled": "boolean",
  "status": "string"
}

Register new user

POST /v1/identity/users

Registers new user based on supplied profile details. Checks whether username, email, phone number are already used

Parameter Type/Format Description
cmd
required

Body /

Command with details of new user

Response

201 - Created

440 - Your request was well constructed but it could not be processed. Consider the following possible problems and look into response for more details: | Problem | Description | |-|-| | [username-already-used]() | Username {username} is already used | | [email-already-used]() | Email address {email} is already used | | [phone-number-already-used]() | Phone number {phone} is already used |

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [error handling](common-getstarted.html#error-handling) 

{}

Get profile of specific user

GET /v1/identity/users/{username}

Retrieves user profile information for specified user

Parameter Type/Format Description
include
optional

Query / Array

List of fields to include in response. For more information see general guidance on [response shaping](common-getstarted.html#shaping)

trim
optional

Query / Array

List of fields to trim from response. For more information see general guidance on [response shaping](common-getstarted.html#shaping)

username
required

Path / String

The username. Username is unique identifier

Response

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [error handling](common-getstarted.html#error-handling)

200 - OK 

{
  "user-id": "string",
  "username": "string",
  "customer-number": "string",
  "last-login": "string",
  "last-answer-validated": "string",
  "last-password-reset": "string",
  "lock-expires": "string",
  "first-name": "string",
  "last-name": "string",
  "email": "string",
  "email-verified": "boolean",
  "phone-number": "string",
  "phone-number-verified": "boolean",
  "hint-picture-url": "string",
  "profile-picture-url": "string",
  "linked-logins": [
    {
      "login": "string",
      "provider": "string"
    }
  ],
  "multifactor-enabled": "boolean",
  "status": "string"
}

Working with policy

Get password quality requirements

GET /v1/identity/policy/password-requirements

Provides password quality requirements to enable better user experience in trusted applications where user inputs passwords

Parameter Type/Format Description

Response

200 - OK

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [error handling](common-getstarted.html#error-handling) 

{
  "length": "integer",
  "non-alphanumeric": "boolean",
  "lowercase": "boolean",
  "uppercase": "boolean",
  "digit": "boolean"
}