Overview

Version information

Version : 1.0.0

URI scheme

Host : cloudentity.dev.cloudentity.com
BasePath : /api
Schemes : HTTPS

Consumes

  • application/json

Produces

  • application/json

Paths

POST /authn/identifierpassword

Description

Authenticates the identified user based on the password supplied.

If authentication succeeds, a new session is created; the session token is returned in the response.

If device print is supplied in the request body and authentication succeeds, the device will be recognized and deviceToken will be issued.

Note that this API returns an Authentication.InvalidCredentials error in either of the following cases: - No user was found by the supplied identifier - The password was incorrect for the identified user - Provided deviceToken doesn’t match supplied in the request body device print

If a session token is provided but is invalid, an Authentication.Unauthenticated error will be returned. If a deviceToken is provided but is invalid, an Authentication.InvalidDeviceToken error will be returned.

Parameters

Type Name Description Schema

Header

deviceToken
optional

Token issued by Devices Service after successfull device recognition

string

Body

body
required

Body of authentication with identifier and password request

IdentifierPasswordAuthenticationRequest

Responses

HTTP Code Description Schema

201

Session was created

SessionCreated

400

Response details:

  • Code : Message

  • Request.Invalid: The request could not be understood by the server due to malformed syntax.

Error

401

Response details:

  • Code : Message

  • Authentication.InvalidCredentials: Invalid credentials.

  • Authentication.Unauthenticated: Not authenticated. This API is only available for authenticated users.

Error

422

Validation error; some of the provided attributes did not pass the validation rules.

Response details:

  • Code: Message

  • User.ValidationError: Some of the attributes did not pass the validation.

  • Details Each of the fields might return one of the following validation error codes.

  • ValidationError.Required

  • ValidationError.Invalid

ValidationError

423

Response details:

  • Code: Message

  • Authentication.Locked: The maximum number of login attempts has been reached.

Error

Tags

  • authn

Security

Type Name

apiKey

SsoToken

Example HTTP response

Response 201
{
  "token" : "1323123-3424324324-4234324324-123123432",
  "deviceToken" : "e09b98e2-c021-41d5-b4a0-4c22f8065817"
}

POST /authn/identifiertotp

Description

Authenticates the identified user based on the time-based one-time password ("TOTP") supplied.

If authentication succeeds, a new session is created; the session token is returned in the response.

If device print is supplied in the request body and authentication succeeds, the device will be recognized and deviceToken will be issued.

Note that this API returns an Authentication.InvalidCredentials error in any of the following cases: - No user was found by the supplied identifier - The user’s authSecret is not yet accepted - The TOTP token was incorrect - If a deviceToken is provided but is invalid, an Authentication.InvalidDeviceToken error will be returned.

If a session token is provided but is invalid, an Authentication.Unauthenticated error will be returned. If a deviceToken is provided but is invalid, an Authentication.InvalidDeviceToken error will be returned.

Parameters

Type Name Description Schema

Header

deviceToken
optional

Token issued by Devices Service after successfull device recognition

string

Body

body
required

Body of authentication with identifier and TOTP request

IdentifierTotpAuthenticationRequest

Responses

HTTP Code Description Schema

201

Session was created

SessionCreated

400

Response details:

  • Code : Message

  • Request.Invalid: The request could not be understood by the server due to malformed syntax.

Error

401

Response details:

  • Code : Message

  • Authentication.InvalidCredentials: Invalid credentials.

  • Authentication.Unauthenticated: Not authenticated. This API is only available for authenticated users.

Error

422

Validation error; some of the provided attributes did not pass the validation rules.

Response details:

  • Code: Message

  • User.ValidationError: Some of the attributes did not pass the validation.

  • Details Each of the fields might return one of the following validation error codes.

  • ValidationError.Required

  • ValidationError.Invalid

ValidationError

Tags

  • authn

Security

Type Name

apiKey

SsoToken

Example HTTP response

Response 201
{
  "token" : "1323123-3424324324-4234324324-123123432",
  "deviceToken" : "e09b98e2-c021-41d5-b4a0-4c22f8065817"
}

POST /authn/kba

Description

Authenticates a user identified by the provided session based on the (case-insensitive) knowledge-based answers supplied.

Upon success, the token will be refreshed and its properties will be updated.

If the provided token is invalid, or the user provides incorrect responses to some questions, an Authentication.Unauthenticated error will be thrown.

If the user has not previously stored responses to KBA questions, a User.KbaNotAccepted error will be thrown.

If the central KBA config allows a user to respond to more more questions than the minimum required, and no challenge questions have been previously set for the user, a User.KbaNotPending error will be thrown.

If the user responds to more questions than the required questions in the current challenge set, a User.ValidationError will be thrown with appropriate details about which questions were extraneous.

Parameters

Type Name Description Schema

Body

body
required

User login data

KbaAuthenticationRequest

Responses

HTTP Code Description Schema

200

Session has been updated

No Content

400

Response details:

  • Code : Message

  • Request.Invalid: The request could not be understood by the server due to malformed syntax.

Error

401

Login unsuccessful

The identifier / KBA responses were not valid.

Detailed reason is returned in the response.

Response detail

  • Code: Message

  • Authentication.InvalidMFA: MFA auth used with the login was incorrect.

  • Authentication.Unauthenticated: Not authenticated. This API is only available for authenticated users.

  • User.KbaNotAccepted: KBA responses have not been set for this user.

  • User.KbaNotPending: KBA responses have not been requested for this user.

Error

404

Response details:

  • Code: Message

  • User.NotFound: User with the given ID does not exist

  • Customer.NotFound: Customer with the given ID does not exist.

  • KbaConfig.NotFound: The KBA config does not exist.

Error

422

Validation error; some of the provided attributes did not pass the validation rules.

Response details:

  • Code: Message

  • User.ValidationError: Some of the attributes did not pass the validation.

  • Details Each of the fields might return one of the following validation error codes.

  • ValidationError.Required

  • ValidationError.Invalid

ValidationError

Tags

  • authn

Security

Type Name

oauth2

oauth2_implicit

oauth2

oauth2_authorizationCode

oauth2

oauth2_password

apiKey

SsoToken

POST /authn/otp

Description

Authenticates a user identified by the provided session based on the one-time password ("OTP") supplied.

Upon success, the token will be refreshed, and its properties will be updated.

OTPs are only acceptable for authentication if they were sent to an identifier address (identifier email or mobile).

Note that this API returns an Authentication.InvalidCredentials error in any of the following cases: - No OTP was stored for the user - The OTP supplied in the request was incorrect - The authentication was attempted using an OTP that had been sent to an unverified identifier

After successful authentication, a call is made to an RSA Notify service with the provided RSA device information.

Parameters

Type Name Description Schema

Body

body
required

Body of authentication with session and OTP request

OtpAuthenticationRequest

Responses

HTTP Code Description Schema

200

Session has been updated

No Content

400

Response details:

  • Code : Message

  • Request.Invalid: The request could not be understood by the server due to malformed syntax.

Error

401

Response details:

  • Code : Message

  • Authentication.InvalidCredentials: Invalid credentials.

  • Authentication.Unauthenticated: Not authenticated. This API is only available for authenticated users.

Error

404

Response details:

  • Code: Message

  • User.NotFound: User with the given ID does not exist

  • Customer.NotFound: Customer with the given ID does not exist.

No Content

422

Validation error; some of the provided attributes did not pass the validation rules.

Response details:

  • Code: Message

  • User.ValidationError: Some of the attributes did not pass the validation.

  • Details Each of the fields might return one of the following validation error codes.

  • ValidationError.Required

  • ValidationError.Invalid

ValidationError

Tags

  • authn

Security

Type Name

oauth2

oauth2_implicit

oauth2

oauth2_authorizationCode

oauth2

oauth2_password

apiKey

SsoToken

POST /authn/password

Description

Authenticates a user identified by the provided session based on the password supplied.

If device print is supplied in the request body and authentication succeeds, the device will be recognized and deviceToken will be issued.

If a deviceToken is provided but is invalid, an Authentication.InvalidDeviceToken error will be returned.

Upon success, the token will be refreshed, and its properties will be updated.

If the password is incorrect for the session user, an Authentication.InvalidCredentials will be returned.

Parameters

Type Name Description Schema

Header

deviceToken
optional

Token issued by Devices Service after successfull device recognition

string

Body

body
required

Body of authentication with session and password request

PasswordAuthenticationRequest

Responses

HTTP Code Description Schema

200

Session has been updated

No Content

400

Response details:

  • Code : Message

  • Request.Invalid: The request could not be understood by the server due to malformed syntax.

Error

401

Response details:

  • Code : Message

  • Authentication.InvalidCredentials: Invalid credentials.

  • Authentication.Unauthenticated: Not authenticated. This API is only available for authenticated users.

Error

404

Response details:

  • Code: Message

  • User.NotFound: User with the given ID does not exist

  • Customer.NotFound: Customer with the given ID does not exist.

No Content

422

Validation error; some of the provided attributes did not pass the validation rules.

Response details:

  • Code: Message

  • User.ValidationError: Some of the attributes did not pass the validation.

  • Details Each of the fields might return one of the following validation error codes.

  • ValidationError.Required

  • ValidationError.Invalid

ValidationError

Tags

  • authn

Security

Type Name

oauth2

oauth2_implicit

oauth2

oauth2_authorizationCode

oauth2

oauth2_password

apiKey

SsoToken

POST /authn/totp

Description

Authenticates a user identified by the provided session based on the time-based one-time password ("TOTP") supplied.

Upon success, the token will be refreshed, and its properties will be updated.

If device print is supplied in the request body and authentication succeeds, the device will be recognized and deviceToken will be issued.

Note that this API returns an Authentication.InvalidCredentials error in either of the following cases: - The user’s authSecret is not yet accepted - The TOTP token was incorrect - Provided deviceToken doesn’t match supplied in the request body device print

If a deviceToken is provided but is invalid, an Authentication.InvalidDeviceToken error will be returned.

Parameters

Type Name Description Schema

Header

deviceToken
optional

Token issued by Devices Service after successfull device recognition

string

Body

body
required

Body of authentication with session and TOTP request

TotpAuthenticationRequest

Responses

HTTP Code Description Schema

200

Session has been updated

No Content

400

Response details:

  • Code : Message

  • Request.Invalid: The request could not be understood by the server due to malformed syntax.

Error

401

Response details:

  • Code : Message

  • Authentication.InvalidCredentials: Invalid credentials.

  • Authentication.Unauthenticated: Not authenticated. This API is only available for authenticated users.

Error

404

Response details:

  • Code: Message

  • User.NotFound: User with the given ID does not exist

  • Customer.NotFound: Customer with the given ID does not exist.

No Content

422

Validation error; some of the provided attributes did not pass the validation rules.

Response details:

  • Code: Message

  • User.ValidationError: Some of the attributes did not pass the validation.

  • Details Each of the fields might return one of the following validation error codes.

  • ValidationError.Required

  • ValidationError.Invalid

ValidationError

423

Response details:

  • Code: Message

  • Authentication.Locked: The maximum number of login attempts has been reached.

Error

Tags

  • authn

Security

Type Name

oauth2

oauth2_implicit

oauth2

oauth2_authorizationCode

oauth2

oauth2_password

apiKey

SsoToken

POST /sla/authn/identifierpassword

Description

Authenticates the identified user based on the password supplied.

If authentication succeeds, a new session is created; the session token is returned in the response.

If device print is supplied in the request body and authentication succeeds, the device will be recognized and deviceToken will be issued.

Note that this API returns an Authentication.InvalidCredentials error in either of the following cases: - No user was found by the supplied identifier - The password was incorrect for the identified user - Provided deviceToken doesn’t match supplied in the request body device print

If a session token is provided but is invalid, an Authentication.Unauthenticated error will be returned. If a deviceToken is provided but is invalid, an Authentication.InvalidDeviceToken error will be returned.

Parameters

Type Name Description Schema

Header

deviceToken
optional

Token issued by Devices Service after successfull device recognition

string

Body

body
required

Body of authentication with identifier and password request

IdentifierPasswordAuthenticationRequest

Responses

HTTP Code Description Schema

201

Session was created

SessionCreated

400

Response details:

  • Code : Message

  • Request.Invalid: The request could not be understood by the server due to malformed syntax.

Error

401

Response details:

  • Code : Message

  • Authentication.InvalidCredentials: Invalid credentials.

  • Authentication.Unauthenticated: Not authenticated. This API is only available for authenticated users.

Error

422

Validation error; some of the provided attributes did not pass the validation rules.

Response details:

  • Code: Message

  • User.ValidationError: Some of the attributes did not pass the validation.

  • Details Each of the fields might return one of the following validation error codes.

  • ValidationError.Required

  • ValidationError.Invalid

ValidationError

423

Response details:

  • Code: Message

  • Authentication.Locked: The maximum number of login attempts has been reached.

Error

Tags

  • authn

Security

Type Name

apiKey

SsoToken

Example HTTP response

Response 201
{
  "token" : "1323123-3424324324-4234324324-123123432",
  "deviceToken" : "e09b98e2-c021-41d5-b4a0-4c22f8065817"
}

POST /sla/authn/identifiertotp

Description

Authenticates the identified user based on the time-based one-time password ("TOTP") supplied.

If authentication succeeds, a new session is created; the session token is returned in the response.

If device print is supplied in the request body and authentication succeeds, the device will be recognized and deviceToken will be issued.

Note that this API returns an Authentication.InvalidCredentials error in any of the following cases: - No user was found by the supplied identifier - The user’s authSecret is not yet accepted - The TOTP token was incorrect - If a deviceToken is provided but is invalid, an Authentication.InvalidDeviceToken error will be returned.

If a session token is provided but is invalid, an Authentication.Unauthenticated error will be returned. If a deviceToken is provided but is invalid, an Authentication.InvalidDeviceToken error will be returned.

Parameters

Type Name Description Schema

Header

deviceToken
optional

Token issued by Devices Service after successfull device recognition

string

Body

body
required

Body of authentication with identifier and TOTP request

IdentifierTotpAuthenticationRequest

Responses

HTTP Code Description Schema

201

Session was created

SessionCreated

400

Response details:

  • Code : Message

  • Request.Invalid: The request could not be understood by the server due to malformed syntax.

Error

401

Response details:

  • Code : Message

  • Authentication.InvalidCredentials: Invalid credentials.

  • Authentication.Unauthenticated: Not authenticated. This API is only available for authenticated users.

Error

422

Validation error; some of the provided attributes did not pass the validation rules.

Response details:

  • Code: Message

  • User.ValidationError: Some of the attributes did not pass the validation.

  • Details Each of the fields might return one of the following validation error codes.

  • ValidationError.Required

  • ValidationError.Invalid

ValidationError

Tags

  • authn

Security

Type Name

apiKey

SsoToken

Example HTTP response

Response 201
{
  "token" : "1323123-3424324324-4234324324-123123432",
  "deviceToken" : "e09b98e2-c021-41d5-b4a0-4c22f8065817"
}

POST /sla/authn/kba

Description

Authenticates a user identified by the provided session based on the (case-insensitive) knowledge-based answers supplied.

Upon success, the token will be refreshed and its properties will be updated.

If the provided token is invalid, or the user provides incorrect responses to some questions, an Authentication.Unauthenticated error will be thrown.

If the user has not previously stored responses to KBA questions, a User.KbaNotAccepted error will be thrown.

If the central KBA config allows a user to respond to more more questions than the minimum required, and no challenge questions have been previously set for the user, a User.KbaNotPending error will be thrown.

If the user responds to more questions than the required questions in the current challenge set, a User.ValidationError will be thrown with appropriate details about which questions were extraneous.

Parameters

Type Name Description Schema

Body

body
required

User login data

KbaAuthenticationRequest

Responses

HTTP Code Description Schema

200

Session has been updated

No Content

400

Response details:

  • Code : Message

  • Request.Invalid: The request could not be understood by the server due to malformed syntax.

Error

401

Login unsuccessful

The identifier / KBA responses were not valid.

Detailed reason is returned in the response.

Response detail

  • Code: Message

  • Authentication.InvalidMFA: MFA auth used with the login was incorrect.

  • Authentication.Unauthenticated: Not authenticated. This API is only available for authenticated users.

  • User.KbaNotAccepted: KBA responses have not been set for this user.

  • User.KbaNotPending: KBA responses have not been requested for this user.

Error

404

Response details:

  • Code: Message

  • User.NotFound: User with the given ID does not exist

  • Customer.NotFound: Customer with the given ID does not exist.

  • KbaConfig.NotFound: The KBA config does not exist.

Error

422

Validation error; some of the provided attributes did not pass the validation rules.

Response details:

  • Code: Message

  • User.ValidationError: Some of the attributes did not pass the validation.

  • Details Each of the fields might return one of the following validation error codes.

  • ValidationError.Required

  • ValidationError.Invalid

ValidationError

Tags

  • authn

Security

Type Name

oauth2

oauth2_implicit

oauth2

oauth2_authorizationCode

oauth2

oauth2_password

apiKey

SsoToken

POST /sla/authn/otp

Description

Authenticates a user identified by the provided session based on the one-time password ("OTP") supplied.

Upon success, the token will be refreshed, and its properties will be updated.

OTPs are only acceptable for authentication if they were sent to an identifier address (identifier email or mobile).

Note that this API returns an Authentication.InvalidCredentials error in any of the following cases: - No OTP was stored for the user - The OTP supplied in the request was incorrect - The authentication was attempted using an OTP that had been sent to an unverified identifier

After successful authentication, a call is made to an RSA Notify service with the provided RSA device information.

Parameters

Type Name Description Schema

Body

body
required

Body of authentication with session and OTP request

OtpAuthenticationRequest

Responses

HTTP Code Description Schema

200

Session has been updated

No Content

400

Response details:

  • Code : Message

  • Request.Invalid: The request could not be understood by the server due to malformed syntax.

Error

401

Response details:

  • Code : Message

  • Authentication.InvalidCredentials: Invalid credentials.

  • Authentication.Unauthenticated: Not authenticated. This API is only available for authenticated users.

Error

404

Response details:

  • Code: Message

  • User.NotFound: User with the given ID does not exist

  • Customer.NotFound: Customer with the given ID does not exist.

No Content

422

Validation error; some of the provided attributes did not pass the validation rules.

Response details:

  • Code: Message

  • User.ValidationError: Some of the attributes did not pass the validation.

  • Details Each of the fields might return one of the following validation error codes.

  • ValidationError.Required

  • ValidationError.Invalid

ValidationError

Tags

  • authn

Security

Type Name

oauth2

oauth2_implicit

oauth2

oauth2_authorizationCode

oauth2

oauth2_password

apiKey

SsoToken

POST /sla/authn/password

Description

Authenticates a user identified by the provided session based on the password supplied.

If device print is supplied in the request body and authentication succeeds, the device will be recognized and deviceToken will be issued.

If a deviceToken is provided but is invalid, an Authentication.InvalidDeviceToken error will be returned.

Upon success, the token will be refreshed, and its properties will be updated.

If the password is incorrect for the session user, an Authentication.InvalidCredentials will be returned.

Parameters

Type Name Description Schema

Header

deviceToken
optional

Token issued by Devices Service after successfull device recognition

string

Body

body
required

Body of authentication with session and password request

PasswordAuthenticationRequest

Responses

HTTP Code Description Schema

200

Session has been updated

No Content

400

Response details:

  • Code : Message

  • Request.Invalid: The request could not be understood by the server due to malformed syntax.

Error

401

Response details:

  • Code : Message

  • Authentication.InvalidCredentials: Invalid credentials.

  • Authentication.Unauthenticated: Not authenticated. This API is only available for authenticated users.

Error

404

Response details:

  • Code: Message

  • User.NotFound: User with the given ID does not exist

  • Customer.NotFound: Customer with the given ID does not exist.

No Content

422

Validation error; some of the provided attributes did not pass the validation rules.

Response details:

  • Code: Message

  • User.ValidationError: Some of the attributes did not pass the validation.

  • Details Each of the fields might return one of the following validation error codes.

  • ValidationError.Required

  • ValidationError.Invalid

ValidationError

Tags

  • authn

Security

Type Name

oauth2

oauth2_implicit

oauth2

oauth2_authorizationCode

oauth2

oauth2_password

apiKey

SsoToken

POST /sla/authn/totp

Description

Authenticates a user identified by the provided session based on the time-based one-time password ("TOTP") supplied.

Upon success, the token will be refreshed, and its properties will be updated.

If device print is supplied in the request body and authentication succeeds, the device will be recognized and deviceToken will be issued.

Note that this API returns an Authentication.InvalidCredentials error in either of the following cases: - The user’s authSecret is not yet accepted - The TOTP token was incorrect - Provided deviceToken doesn’t match supplied in the request body device print

If a deviceToken is provided but is invalid, an Authentication.InvalidDeviceToken error will be returned.

Parameters

Type Name Description Schema

Header

deviceToken
optional

Token issued by Devices Service after successfull device recognition

string

Body

body
required

Body of authentication with session and TOTP request

TotpAuthenticationRequest

Responses

HTTP Code Description Schema

200

Session has been updated

No Content

400

Response details:

  • Code : Message

  • Request.Invalid: The request could not be understood by the server due to malformed syntax.

Error

401

Response details:

  • Code : Message

  • Authentication.InvalidCredentials: Invalid credentials.

  • Authentication.Unauthenticated: Not authenticated. This API is only available for authenticated users.

Error

404

Response details:

  • Code: Message

  • User.NotFound: User with the given ID does not exist

  • Customer.NotFound: Customer with the given ID does not exist.

No Content

422

Validation error; some of the provided attributes did not pass the validation rules.

Response details:

  • Code: Message

  • User.ValidationError: Some of the attributes did not pass the validation.

  • Details Each of the fields might return one of the following validation error codes.

  • ValidationError.Required

  • ValidationError.Invalid

ValidationError

423

Response details:

  • Code: Message

  • Authentication.Locked: The maximum number of login attempts has been reached.

Error

Tags

  • authn

Security

Type Name

oauth2

oauth2_implicit

oauth2

oauth2_authorizationCode

oauth2

oauth2_password

apiKey

SsoToken

Definitions

AliveStatus

Name Description Schema

message
optional

Description of service status if available

string

Error

Name Description Schema

code
optional

Unique internal error code

string

details
optional

Optional. Varies depending on the specific use case - details are determined by the particular API call.

object

message
optional

Description of the error code

string

IdentifierPasswordAuthenticationRequest

Name Description Schema

device
optional

device

identifier
optional

User unique identifier

string

password
optional

User password

string

device

Name Schema

name
optional

string

properties
optional

properties

type
optional

enum (android, windows, desktop, ios, browser)

properties

Name Description Schema

details
optional

Detailed device information

object

platform
optional

platform

platform

Name Schema

name
optional

string

version
optional

string

IdentifierTotpAuthenticationRequest

Name Description Schema

device
optional

device

identifier
optional

User unique identifier

string

totpToken
optional

TOTP token value

string

device

Name Schema

name
optional

string

properties
optional

properties

type
optional

enum (android, windows, desktop, ios, browser)

properties

Name Description Schema

details
optional

Detailed device information

object

platform
optional

platform

platform

Name Schema

name
optional

string

version
optional

string

KbaAuthenticationRequest

Name Description Schema

kbaResponseSet
optional

KBA response questions and answers

< kbaResponseSet > array

kbaResponseSet

Name Description Schema

questionIdentifier
optional

Unique identifier for a KBA question

string

response
optional

User’s plaintext answer to a KBA question

string

OtpAuthenticationRequest

Name Description Schema

otp
optional

OTP value

string

PasswordAuthenticationRequest

Name Description Schema

password
optional

User password

string

SessionCreated

Name Schema

deviceToken
optional

string

token
optional

string

TotpAuthenticationRequest

Name Description Schema

totpToken
optional

TOTP token value

string

ValidationError

Name Description Schema

code
optional

Unique internal error code

string

details
optional

details

message
optional

Description of the error code

string

details

Name Schema

fields
optional

< fields > array

fields

Name Description Schema

code
optional

Unique internal error code

string

message
optional

Description of the error code

string

name
optional

Name of the field

string

VerifyIdentifierPasswordCredentialsRequest

Name Description Schema

identifier
optional

User identifier

string

password
optional

User password

string

Security

SsoToken

Type : apiKey
Name : token
In : HEADER

oauth2_implicit

Type : oauth2
Flow : implicit
Token URL : https://cloudentity.dev.cloudentity.com/oauth/authorize

oauth2_authorizationCode

Type : oauth2
Flow : accessCode
Token URL : https://cloudentity.dev.cloudentity.com/oauth/authorize
Token URL : https://cloudentity.dev.cloudentity.com/oauth/token

oauth2_password

Type : oauth2
Flow : password
Token URL : https://cloudentity.dev.cloudentity.com/oauth/token