Api documentation
Learn how to get started with our Api 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
|
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
|
Body / |
Security answer validation request |
username
|
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
|
Path / String |
The username. Username is unique identifier |
cmd
|
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
|
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
|
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
|
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
|
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
|
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
|
Path / String |
The username. Username is unique identifier |
cmd
|
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
|
Path / String |
The username. Username is unique identifier |
cmd
|
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
|
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
|
Path / String |
The username. Username is unique identifier |
cmd
|
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
|
Query / Array |
List of fields to include in response. For more information see general guidance on [response shaping](common-getstarted.html#shaping) |
trim
|
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
|
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
|
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
|
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
|
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
|
Query / String |
The username. Username is unique identifier |
email
|
Query / String |
The username. Username is unique identifier |
include
|
Query / Array |
List of fields to include in response. For more information see general guidance on [response shaping](common-getstarted.html#shaping) |
login
|
Query / String |
The username. Username is unique identifier |
phone-number
|
Query / String |
The username. Username is unique identifier |
trim
|
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
|
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
|
Query / Array |
List of fields to include in response. For more information see general guidance on [response shaping](common-getstarted.html#shaping) |
trim
|
Query / Array |
List of fields to trim from response. For more information see general guidance on [response shaping](common-getstarted.html#shaping) |
username
|
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"
}