Cloudentity APIs API Reference

Note: This document is addressed to developers and people with some understanding of REST APIs.

Cloudentity exposes several APIs for developers to interact with:


User APIs: Reading and managing your user account
Authentication APIs: Basic SSO (Single Sign On) authentication
Session APIs: SSO session operations
Device APIs: Managing used devices
Access Policy APIs: Access policy (authorization)
KBA APIs: Knowledge-based authentication
Oauth APIs: OAuth 2.0 endpoint following Oauth RFC specification
Openid APIs: OpenID UserInfo API

Note: APIs listed on this page represent a sample of the full Cloudentity APIs specification.

If you want to easily try out some of the APIs, you can use Postman or curl.

Sample curl call:

curl -X POST "https://demo.cloudentity.com/api/authn/identifierpassword"
-H "Content-Type: application/json"
-d '{"identifier":"REPLACE_WITH_UID","password":"REPLACE_WITH_PASSWORD"}'

Sample output:

{"token":"f00ebab8-a7bf-48e6-9c4c-2e3a437ac778"}
API Endpoint
https://demo.cloudentity.com/api
Request Content-Types: application/json
Response Content-Types: application/json
Schemes: https
Version: 1.0.0

user

User APIs allow you to access and change the state of your user account. You can do the following (among others):

  • access/edit your profile
  • activate your account
  • change your password
  • manage your TOTP secret

POST /user

Register user (self service).

If uid is provided, it may not be email or mobile formatted; otherwise, a User.ValidationError will be returned.

If the provided uid, email or mobile is among another user's identifiers, a User.Duplicate error will be returned.

If the resolved customer does not exist, a Customer.NotFound error will be returned.

If allowPublicRegistration is set to false then a Customer.NotFound error will be returned.

A set of (case-insensitive) responses to KBA questions may optionally be supplied and stored with the created user record. The supplied response set will be validated according to the following rules:

  • No duplicate question identifers may be supplied
  • Question identifiers must be among the available, system-configured KBA questions
  • The system-configured kbaMinQuestionsPerUser sets the lower bound of the questions which must be answered for each user; no fewer than this number of questions must be answered.
  • The system-configured kbaMaxQuestionsPerUser sets the upper bound of the questions which may be answered for each user; no more than this number of questions must be answered. If any of these rules is violated, a User.ValidationError will be returned with a description of which rule was violated.
customer
in query
string

CID of the customer to which this user is assigned

realm
in query
string

User's realm. If not sent, default realm is used.

Request Example
{
  "uid": "jdoe12",
  "password": "s0M3#P@ssw0rd",
  "firstName": "Joe",
  "lastName": "Doe",
  "email": "jdoe@cloudentity.com",
  "mobile": "99123456789",
  "mfaMethod": "NONE",
  "kbaResponseSet": [
    {
      "questionIdentifier": "msq0",
      "response": "Baseball"
    }
  ],
  "otpMethod": "E"
}
201 Created

User successfully registered.

400 Bad Request

Response details:

  • Code : Message
  • Request.Invalid: The request could not be understood by the server due to malformed syntax.
404 Not Found

Response details:

  • Code: Message
  • Customer.NotFound: Customer with the given ID does not exist.
409 Conflict

Response details:

  • Code : Message
  • User.Duplicate: At least one of the provided user identifiers is not unique.
  • Details:

  • duplicateIdentifiers field consists of list of fields which should be unique, but there was already a user with that identifier

422 Unprocessable Entity

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

Response Example (201 Created)
{
  "uuid": "eaf993f8-2774-4666-ac7a-ec6c430d3c60"
}
Response Example (400 Bad Request)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (409 Conflict)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "duplicateIdentifiers": [
      "uid"
    ]
  }
}
Response Example (422 Unprocessable Entity)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "fields": [
      {
        "name": "uid",
        "code": "errorCode",
        "message": "errorMessage"
      }
    ]
  }
}

GET /user

Get the current user's record.

The current user is identified by the SSO token or OAuth Access Token.

This service requires the SELF_GET_USER entitlement.

token
in header
string

SSO token of the current user

Authorization
in header
string

OAuth Access Token of the current user

200 OK

The self view of the user record is returned.

400 Bad Request

Response details:

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

Response details:

  • Code : Message
  • Authentication.Unauthenticated: Not authenticated. This API is only available for authenticated users.
403 Forbidden

Response details:

  • Code : Message
  • Authorization.Unauthorized: Not authorized. This API is only available for authorized users.
404 Not Found

Response details:

  • Code : Message
  • User.NotFound: User with the given ID does not exist
Response Example (200 OK)
{
  "uuid": "eaf993f8-2774-4666-ac7a-ec6c430d3c60",
  "uid": "jdoe12",
  "unverifiedEmails": [
    "jdoe2@cloudentity.com"
  ],
  "unverifiedMobiles": [
    "99987654321"
  ],
  "verifiedEmails": [
    "jdoe@cloudentity.com"
  ],
  "verifiedMobiles": [
    "99123456789"
  ],
  "identifierEmails": [
    "jdoe@cloudentity.com"
  ],
  "identifierMobiles": [
    "99123456789"
  ],
  "kbaQuestionSet": [
    "msq0"
  ],
  "firstName": "Joe",
  "forcePwdReset": false,
  "lastName": "Doe",
  "mfaMethod": "NONE",
  "locale": "en_GB",
  "dob": "2010-02-02",
  "gender": "M",
  "address": "2815 2nd Ave, Suite 390",
  "city": "Seattle",
  "locality": "Washington",
  "country": "USA",
  "postalCode": "WA 98121",
  "organization": "Cloudentity",
  "defaultEmail": "jdoe@cloudentity.com",
  "defaultMobile": "99123456789",
  "status": "active",
  "entitlements": [
    "ACCESS_TO_APPLICATION1"
  ],
  "entitlementGroups": [
    "ACCESS_TO_ALL_APPLICATIONS"
  ],
  "googleAuthSecretAccepted": "false",
  "apiKey": "rk3bt35bt4ht4oi2goig43ut3otirni3rn3orn2ir",
  "completeEntitlements": [
    "ACCESS_TO_ALL_APPLICATIONS",
    "ACCESS_TO_APPLICATION1"
  ],
  "customer": "<Your subdomain before demo.cloudentity.com>",
  "eulaApproval": "false",
  "eulaRevision": "1",
  "newUserStatus": true,
  "otpMethod": "E",
  "otpMfaDestination": "jdoe@cloudentity.com",
  "otpSetupComplete": true
}
Response Example (400 Bad Request)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (401 Unauthorized)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (403 Forbidden)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (404 Not Found)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}

PUT /user

Update the current user's record.

The current user is identified by the SSO token or OAuth Access Token.

If defaultEmail or defaultMobile is provided but is not among the this user's verified or identifier emails or mobiles, a User.EmailNotFound or User.MobileNotFound error will be returned, respectively.

This service requires the SELF_UPDATE_USER entitlement.

token
in header
string

SSO token of the current user

Authorization
in header
string

OAuth Access Token of the current user

Request Example
{
  "firstName": "Joe",
  "lastName": "Doe",
  "locale": "en_GB",
  "dob": "2010-02-02",
  "gender": "M",
  "address": "2815 2nd Ave, Suite 390",
  "city": "Seattle",
  "locality": "Washington",
  "country": "USA",
  "postalCode": "WA 98121",
  "mfaMethod": "NONE",
  "defaultEmail": "jdoe@cloudentity.com",
  "defaultMobile": "99123456789",
  "newUserStatus": true,
  "otpMethod": "E"
}
200 OK

User is updated, the self view of the user record is returned.

400 Bad Request

Response details:

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

Response details:

  • Code : Message
  • Authentication.Unauthenticated: Not authenticated. This API is only available for authenticated users.
403 Forbidden

Response details:

  • Code : Message
  • Authorization.Unauthorized: Not authorized. This API is only available for authorized users.
404 Not Found

Response details:

  • Code : Message
  • User.NotFound: User with the given ID does not exist
  • User.EmailNotFound: The requested address was not found among this user's emails.
  • User.MobileNotFound: The requested address was not found among this user's mobiles.
409 Conflict

Response details:

  • Code : Message
  • User.Duplicate: At least one of the provided user identifiers is not unique.
  • Details:

  • duplicateIdentifiers field consists of list of fields which should be unique, but there was already a user with that identifier

422 Unprocessable Entity

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

Response Example (200 OK)
{
  "uuid": "eaf993f8-2774-4666-ac7a-ec6c430d3c60",
  "uid": "jdoe12",
  "unverifiedEmails": [
    "jdoe2@cloudentity.com"
  ],
  "unverifiedMobiles": [
    "99987654321"
  ],
  "verifiedEmails": [
    "jdoe@cloudentity.com"
  ],
  "verifiedMobiles": [
    "99123456789"
  ],
  "identifierEmails": [
    "jdoe@cloudentity.com"
  ],
  "identifierMobiles": [
    "99123456789"
  ],
  "kbaQuestionSet": [
    "msq0"
  ],
  "firstName": "Joe",
  "forcePwdReset": false,
  "lastName": "Doe",
  "mfaMethod": "NONE",
  "locale": "en_GB",
  "dob": "2010-02-02",
  "gender": "M",
  "address": "2815 2nd Ave, Suite 390",
  "city": "Seattle",
  "locality": "Washington",
  "country": "USA",
  "postalCode": "WA 98121",
  "organization": "Cloudentity",
  "defaultEmail": "jdoe@cloudentity.com",
  "defaultMobile": "99123456789",
  "status": "active",
  "entitlements": [
    "ACCESS_TO_APPLICATION1"
  ],
  "entitlementGroups": [
    "ACCESS_TO_ALL_APPLICATIONS"
  ],
  "googleAuthSecretAccepted": "false",
  "apiKey": "rk3bt35bt4ht4oi2goig43ut3otirni3rn3orn2ir",
  "completeEntitlements": [
    "ACCESS_TO_ALL_APPLICATIONS",
    "ACCESS_TO_APPLICATION1"
  ],
  "customer": "<Your subdomain before demo.cloudentity.com>",
  "eulaApproval": "false",
  "eulaRevision": "1",
  "newUserStatus": true,
  "otpMethod": "E",
  "otpMfaDestination": "jdoe@cloudentity.com",
  "otpSetupComplete": true
}
Response Example (400 Bad Request)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (401 Unauthorized)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (403 Forbidden)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (404 Not Found)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (409 Conflict)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "duplicateIdentifiers": [
      "uid"
    ]
  }
}
Response Example (422 Unprocessable Entity)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "fields": [
      {
        "name": "uid",
        "code": "errorCode",
        "message": "errorMessage"
      }
    ]
  }
}

POST /user/activation/email

Activates user account using a verification code sent to a user's email address.

Upon success, the user will be activated and any existing sessions will be invalidated. If password is provided and forcePwdReset is true, password is updated. If configuration attribute withSession is true and body parameter issueSession is true, API will return session token

Additionally, the email address to which the activation link was sent will be upgraded from unverified to verified, and set as the default email if none already exists. If the system configuration areVerifiedAddressesIdentifiers is set to true, the email will be added to the user's identifier emails.

The user must be inactive. If the supplied code corresponds to an active user, a User.Active error will be returned.

A User.VerificationCodeInvalid error may be generated by any of the following conditions:

  • The supplied verification code is malformed
  • A new verification code has been sent, superseding the current code

A Request.Gone error may be generated by any of the following conditions:

  • No code has been generated for this user
  • The code has expired
  • The code has been removed because the maximum number of failed attempts has been exceeded

A Request.Invalid error may be generated by any of the following conditions:

  • forcePwdReset is false and password is provided
  • forcePwdReset is true and password is not provided
Request Example
{
  "code": "DhpOExCODIrWU94UnBBa3JYdzB=",
  "password": "s0M3#P@ssw0rd",
  "issueSession": false
}
200 OK

Account activated successfully and session was created

204 No Content

Account activated successfully.

400 Bad Request

Response details:

  • Code : Message
  • Request.Invalid: The request could not be understood by the server due to malformed syntax.
  • User.Active: User account is active.
410 Gone

Response details:

  • Code: Message
  • Request.Gone: Link expired and is no longer available at this location.
422 Unprocessable Entity

Provided code is not a valid verification code.

Response details:

  • Code : Message
  • User.VerificationCodeInvalid: Verification code is not valid
Response Example (200 OK)
{
  "token": "fc511734-8662-47f0-baeb-8accc4635d89"
}
Response Example (400 Bad Request)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (410 Gone)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (422 Unprocessable Entity)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}

POST /user/activation/send

Generates and sends an activation link to an inactive user's unverified email (via SMTP), or a one-time password ("OTP") to a user's unverified mobile (via SMS).

The destination address is based on the destination and deliveryMode request parameters, as well as the user's existing unverified emails and mobiles and the otpMethod attribute:

  • If destination is specified and corresponds to one of the user's unverified emails or mobiles, the message is sent to this destination.
  • If destination is not specified, the message is sent to the user's first unverified email or mobile based on the user's otpMethod
  • If destination is not specified and the user's otpMethod is not set, the user's first unverified email will be used.

A Request.Invalid error will be returned in any of the following scenarios:

  • The user is not found
  • The user is already active
  • The destination parameter is specified but the user has no such unverified email or mobile
Request Example
{
  "identifier": "jdoe12",
  "destination": "jdoe2@cloudentity.com"
}
204 No Content

An activation message was successfully generated and sent to the user's email or mobile.

400 Bad Request

Response details:

  • Code : Message
  • Request.Invalid: The request could not be understood by the server due to malformed syntax.
422 Unprocessable Entity

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

Response Example (400 Bad Request)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (422 Unprocessable Entity)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "fields": [
      {
        "name": "uid",
        "code": "errorCode",
        "message": "errorMessage"
      }
    ]
  }
}

PUT /user/password

Changes a user's password, using a session and the old password for verification.

This service requires the SELF_CHANGE_PASSWORD entitlement.

token
in header
string

SSO token of the current user

Authorization
in header
string

OAuth Access Token of the current user

Request Example
{
  "oldPassword": "s0M3#P@ssw0rd",
  "newPassword": "0th3r#P@ssw0rd"
}
204 No Content

The user's password was successfully changed.

400 Bad Request

Response details:

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

Response details:

  • Code : Message
  • Authentication.Unauthenticated: Not authenticated. This API is only available for authenticated users.
422 Unprocessable Entity

Response details:

  • Code : Message
  • User.InvalidOldPassword: Old password is invalid.
  • User.InvalidNewPassword: New password is invalid (new password is the same as old one or does not match password policy rules)
Response Example (400 Bad Request)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (401 Unauthorized)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (422 Unprocessable Entity)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}

POST /user/identifier

Add an unverified email or mobile to the current user.

Only one new address (email or mobile) can be added per request. If both email and mobile are supplied in the same request, a User.ValidationError will be returned.

If the new address is already among this user's unverified or verified emails or mobiles, a User.ValidationError will be returned with details indicating which field(s) contain the address.

If the system configuration areVerifiedAddressesIdentifiers is set to true, and the new address is already among another user's identifier addresses, a User.Duplicate error will be returned.

The "SELF_ADD_EMAIL_OR_MOBILE" entitlement is required.

token
in header
string

SSO token of the current user

Authorization
in header
string

OAuth Access Token of the current user

Request Example
{
  "email": "jdoe2@cloudentity.com",
  "mobile": "99987654321"
}
204 No Content

The unverified identifier was successfully added to this user.

400 Bad Request

Response details:

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

Response details:

  • Code : Message
  • Authentication.Unauthenticated: Not authenticated. This API is only available for authenticated users.
403 Forbidden

Response details:

  • Code : Message
  • Authorization.Unauthorized: Not authorized. This API is only available for authorized users.
404 Not Found

Response details:

  • Code : Message
  • User.NotFound: User with the given ID does not exist
409 Conflict

Response details:

  • Code : Message
  • User.Duplicate: At least one of the provided user identifiers is not unique.
  • Details:

  • duplicateIdentifiers field consists of list of fields which should be unique, but there was already a user with that identifier

422 Unprocessable Entity

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

Response Example (400 Bad Request)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (401 Unauthorized)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (403 Forbidden)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (404 Not Found)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (409 Conflict)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "duplicateIdentifiers": [
      "uid"
    ]
  }
}
Response Example (422 Unprocessable Entity)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "fields": [
      {
        "name": "uid",
        "code": "errorCode",
        "message": "errorMessage"
      }
    ]
  }
}

POST /user/identifier/verification/send

Generates and sends a verification code to a user's unverified or verified email or mobile.

If the destination resolves to an email, and the codeType request parameter is "E" (encrypted code), an encrypted verification code will be sent to the specified email. Otherwise, a plaintext OTP will be sent to the email or mobile. Note that if the destination is a mobile address, the code type will always be plaintext OTP.

If the destination is not among this user's unverified or verified emails or mobiles, a User.AddressNotFound error will be returned.

The deliveryMode parameter must be supplied to specify which delivery mode to use. Allowable combinations are:

  • For email address: E (SMTP)
  • For mobile address: M (SMS)
  • For mobile address: V (VOICE)

If the deliveryMode is not valid for the destination identified, a User.OtpDeliveryModeInvalid error will be returned, with details describing the invalid combination.

The SELF_SEND_VERIFICATION_CODE entitlement is required.

token
in header
string

SSO token of the current user

Authorization
in header
string

OAuth Access Token of the current user

Request Example
{
  "destination": "jdoe2@cloudentity.com",
  "deliveryMode": "E",
  "codeType": "P"
}
202 Accepted

A verification code was successfully generated and sent to the user's email or mobile.

400 Bad Request

Response details:

  • Code : Message
  • Request.Invalid: The request could not be understood by the server due to malformed syntax.
  • User.OtpDeliveryModeInvalid: Invalid OTP delivery mode for the specified destination
404 Not Found

Response details:

  • Code: Message
  • User.AddressNotFound: The requested address was not found among this user's emails or mobiles.
422 Unprocessable Entity

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

Response Example (202 Accepted)
{
  "sendInfo": {
    "destination": "jdoe@cloudentity.com",
    "destinationType": "EMAIL",
    "deliveryMode": "EMAIL",
    "codeType": "PLAINTEXT"
  }
}
Response Example (400 Bad Request)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (404 Not Found)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (422 Unprocessable Entity)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "fields": [
      {
        "name": "uid",
        "code": "errorCode",
        "message": "errorMessage"
      }
    ]
  }
}

POST /user/identifier/verification/confirm

Verifies a user's email or mobile based on a one-time password (OTP) or encrypted code sent to the address.

If the request code param is an OTP, the identifier param must also be supplied in order to identify the user.

Upon success, if the identifier was unverified, it will be upgraded from unverified to verified, and set as the default email or mobile if none already exists. If the system configuration areVerifiedAddressesIdentifiers is set to true, the email or mobile will also be added to the user's identifier emails or mobiles. No change occurs if the identifier was already verified.

An Authentication.InvalidCredentials error may be generated by any of the following conditions:

  • The user is not found by the supplied identifier or encrypted code
  • The supplied verification code is incorrect

A Request.Gone error may be generated by any of the following conditions:

  • No verification code has been generated for this user
  • The verification code has expired
  • The verification code has been removed because the maximum number of failed attempts has been exceeded

If the encrypted verification code is malformed, a User.VerificationCodeInvalid error will be generated.

Request Example
{
  "code": "123456",
  "identifier": "jdoe12"
}
204 No Content

The identifier was successfully verified.

400 Bad Request

Response details:

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

Response details:

  • Code : Message
  • Authentication.InvalidCredentials: Invalid credentials.
410 Gone

Response details:

  • Code: Message
  • Request.Gone: Link expired and is no longer available at this location.
422 Unprocessable Entity

Provided code is not a valid verification code.

Response details:

  • Code : Message
  • User.VerificationCodeInvalid: Verification code is not valid
Response Example (400 Bad Request)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (401 Unauthorized)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (410 Gone)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (422 Unprocessable Entity)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}

POST /user/identifiers/remove

Removes requested identifiers or addresses from a user. Any valid identifier values supplied in the identifiers list in the request will be removed.

Any identifier from the following categories may be removed:

  • UID
  • verified emails
  • verified mobiles
  • identifier emails
  • identifier mobiles

Note: It is not possible to remove a user's UUID.

If all of the supplied identifiers are found in the user record, 204 NO CONTENT will be returned. If at least one identifier is not found or is not removable, 200 OK will be returned; successfully removed identifiers are returned in the successful list of the response body, and unsuccessfully removed identifiers are returned in the unsuccessful list.

If a removed identifier corresponds to the user's current default email or mobile, the default email or mobile will be adjusted to the first available verified email or mobile, respectively. If no verified emails or mobiles remain after removal, the default email or mobile will be removed as well.

If a removed identifier corresponds to the user's current otpMfaDestination, the otpMfaDestination will be removed and otpSetupComplete attribute will be set to false.

Warning: It is possible to remove all of a user's human-recognizable (non-UUID) identifiers. This could prevent future authentications and administrative actions unless the UUID is known to the user or acting admin.

A User.ValidationError will be thrown if the requested identifiers list meets any of the following conditions:

  • The list is empty
  • The list contains empty elements
  • The list contains duplicate elements
  • The list contains more than 10 elements

This service requires the SELF_REMOVE_IDENTIFIERS entitlement.

List of identifiers

List of identifiers

identifiers: string[]
token
in header
string

SSO token of the current user

Authorization
in header
string

OAuth Access Token of the current user

Request Example
{
  "identifiers": [
    "99987654321",
    "99987654320"
  ]
}
200 OK

Some requested identifiers could not be removed

204 No Content

All requested identifiers were successfully removed

400 Bad Request

Response details:

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

Response details:

  • Code : Message
  • Authentication.Unauthenticated: Not authenticated. This API is only available for authenticated users.
403 Forbidden

Response details:

  • Code : Message
  • Authorization.Unauthorized: Not authorized. This API is only available for authorized users.
422 Unprocessable Entity

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

Response Example (200 OK)
{
  "successful": [
    "99987654321"
  ],
  "unsuccessful": [
    "99987654320"
  ]
}
Response Example (400 Bad Request)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (401 Unauthorized)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (403 Forbidden)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (422 Unprocessable Entity)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "fields": [
      {
        "name": "uid",
        "code": "errorCode",
        "message": "errorMessage"
      }
    ]
  }
}

POST /user/password/reset/request

Requests a password reset process start (sending an email with reset link).

Only the user's UID will be accepted as an identifier. Once the user is identified, their defaultEmail address will be used as the destination of the password-reset email.

For security purposes, a success status will be returned for all valid requests, even if the identifier does not correspond to an existing user's UID.

The identified user's current mfaMethod will also be included in the password-reset link to facilitate multi-factor authentication during the confirmation step.

Request Example
{
  "identifier": "jdoe12"
}
202 Accepted

Accepted; an email should arrive in the provided email's inbox soon.

400 Bad Request

Response details:

  • Code : Message
  • Request.Invalid: The request could not be understood by the server due to malformed syntax.
Response Example (400 Bad Request)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}

POST /user/password/reset/confirm

Confirm password reset using received code. Upon success:

  • The user is activated
  • The user's password is set
  • All existing sessions of the user are invalidated
  • The email to which the code was sent will be upgraded from unverified to verified
  • The email to which the code was sent will be set as the default email if none already exists
  • If the system configuration areVerifiedAddressesIdentifiers is set to true, the email will be added to the user's identifier emails.

If the system configuration allowResetViaUnverifiedAddress is set to false and the email to which the code was sent was unverified, a User.ValidationError will be returned.

A User.VerificationCodeInvalid error will be returned in any of the following scenarios:

  • The supplied code is malformed
  • The supplied code corresponds to a missing or deleted user
  • A new code has been sent, superseding the supplied code

A Request.Gone error will be returned in any of the following scenarios:

  • No code has been generated for this user
  • The code has expired
  • The code has been removed because the maximum number of failed attempts has been exceeded
Request Example
{
  "code": "DhpOExCODIrWU94UnBBa3JYdzB=",
  "password": "0th3r#P@ssw0rd",
  "googlekey": "654321"
}
200 OK

Password was re-set successfully.

400 Bad Request

Response details:

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

Response details:

  • Code: Message
  • Request.Gone: Link expired and is no longer available at this location.
422 Unprocessable Entity

Response details:

  • Code: Message
  • User.ValidationError: Some of the attributes did not pass the validation.
  • User.VerificationCodeInvalid: Verification code is not valid
Response Example (400 Bad Request)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (410 Gone)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (422 Unprocessable Entity)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "fields": [
      {
        "name": "uid",
        "code": "errorCode",
        "message": "errorMessage"
      }
    ]
  }
}

GET /user/authsecret

View the current user's Google auth secret.

The auth secret can only be viewed if it has not been previously confirmed by the user.

This service requires the SELF_GET_AUTH_SECRET entitlement.

token
in header
string

SSO token of the current user

200 OK

The user's current auth secret is returned.

400 Bad Request

Response details:

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

Response details:

  • Code : Message
  • Authentication.Unauthenticated: Not authenticated. This API is only available for authenticated users.
403 Forbidden

Response details:

  • Code : Message
  • Authorization.Unauthorized: Not authorized. This API is only available for authorized users.
  • User.AuthSecretAlreadyAccepted: The auth secret has already been accepted.
Response Example (200 OK)
{
  "googleAuthSecret": "string"
}
Response Example (400 Bad Request)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (401 Unauthorized)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (403 Forbidden)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}

PUT /user/authsecret

Reset the current user's Google auth secret.

A new authSecret is generated and stored for the current user, and the googleAuthSecretAccepted is set to false, enabling the user to view the new authSecret.

This service requires the SELF_RESET_AUTH_SECRET entitlement.

token
in header
string

SSO token of the current user

204 No Content

The new auth secret for the user is generated.

400 Bad Request

Response details:

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

Response details:

  • Code : Message
  • Authentication.Unauthenticated: Not authenticated. This API is only available for authenticated users.
403 Forbidden

Response details:

  • Code : Message
  • Authorization.Unauthorized: Not authorized. This API is only available for authorized users.
422 Unprocessable Entity

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

Response Example (400 Bad Request)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (401 Unauthorized)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (403 Forbidden)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (422 Unprocessable Entity)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "fields": [
      {
        "name": "uid",
        "code": "errorCode",
        "message": "errorMessage"
      }
    ]
  }
}

POST /user/authsecret/confirm

Confirms the current user's Google auth secret by validating a Google one-time key.

This api invalidates all sessions of a user.

This service requires the SELF_CONFIRM_AUTH_SECRET entitlement.

token
in header
string

SSO token of the current user

Request Example
{
  "googlekey": "654321"
}
204 No Content

The user's auth secret was successfully confirmed.

400 Bad Request

Response details:

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

Response details:

  • Code : Message
  • Authentication.Unauthenticated: Not authenticated. This API is only available for authenticated users.
  • Authentication.InvalidMFA: MFA auth used with the login was incorrect.
403 Forbidden

Response details:

  • Code : Message
  • Authorization.Unauthorized: Not authorized. This API is only available for authorized users.
  • User.AuthSecretAlreadyAccepted: The auth secret has already been accepted.
422 Unprocessable Entity

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

Response Example (400 Bad Request)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (403 Forbidden)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (422 Unprocessable Entity)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "fields": [
      {
        "name": "uid",
        "code": "errorCode",
        "message": "errorMessage"
      }
    ]
  }
}

authn

Authentication APIs allow you to log in with:

  • password
  • TOTP

POST /authn/identifierpassword

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.

token
in header
string

SSO token of the current user

deviceToken
in header
string

Token issued by Devices Service after successfull device recognition

Request Example
{
  "identifier": "jdoe12",
  "password": "s0M3#P@ssw0rd",
  "device": {
    "name": "Chrome",
    "type": "browser",
    "properties": {
      "platform": {
        "name": "Chrome",
        "version": "64.0.3282.140"
      },
      "details": {
        "os": {
          "name": "Mac OS",
          "version": "10.13.0"
        }
      }
    }
  }
}
201 Created

Session was created

400 Bad Request

Response details:

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

Response details:

  • Code : Message
  • Authentication.InvalidCredentials: Invalid credentials.
  • Authentication.Unauthenticated: Not authenticated. This API is only available for authenticated users.
422 Unprocessable Entity

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

Response Example (201 Created)
{
  "token": "fc511734-8662-47f0-baeb-8accc4635d89",
  "deviceToken": "e5e171cc-12d2-40bc-ad14-98a98ad3ab47"
}
Response Example (400 Bad Request)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (401 Unauthorized)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (422 Unprocessable Entity)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "fields": [
      {
        "name": "uid",
        "code": "errorCode",
        "message": "errorMessage"
      }
    ]
  }
}

POST /authn/totp

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.

token
in header
string

SSO token of the current user

deviceToken
in header
string

Token issued by Devices Service after successfull device recognition

Request Example
{
  "totpToken": "123456"
}
201 Created

Session was created

400 Bad Request

Response details:

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

Response details:

  • Code : Message
  • Authentication.InvalidCredentials: Invalid credentials.
  • Authentication.Unauthenticated: Not authenticated. This API is only available for authenticated users.
404 Not Found

Response details:

  • Code: Message
  • User.NotFound: User with the given ID does not exist
  • Customer.NotFound: Customer with the given ID does not exist.
422 Unprocessable Entity

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

Response Example (201 Created)
{
  "token": "fc511734-8662-47f0-baeb-8accc4635d89",
  "deviceToken": "e5e171cc-12d2-40bc-ad14-98a98ad3ab47"
}
Response Example (400 Bad Request)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (401 Unauthorized)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (422 Unprocessable Entity)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "fields": [
      {
        "name": "uid",
        "code": "errorCode",
        "message": "errorMessage"
      }
    ]
  }
}

session

Session APIs allow you to manage your session

  • get it's contents
  • verify it's validity
  • delete it (logout)

GET /session

Gets user's current session details

token
in header
string

SSO token of the current user

200 OK

Current user session details

400 Bad Request

Response details:

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

Response details:

  • Code : Message
  • Authentication.Unauthenticated: Not authenticated. This API is only available for authenticated users.
Response Example (200 OK)
{
  "authenticationIdentifier": "jdoe12",
  "authLevel": 35,
  "customer": "<Your subdomain before demo.cloudentity.com>",
  "customerAlias": "<Your user friendly alias from subdomain before demo.cloudentity.com>",
  "defaultCustomer": "<Your subdomain before demo.cloudentity.com>",
  "defaultCustomerStatus": "active",
  "entitlementGroups": [
    "ACCESS_TO_ALL_APPLICATIONS"
  ],
  "entitlements": [
    "ACCESS_TO_APPLICATION_X"
  ],
  "firstName": "Joe",
  "googleAuthSecretAccepted": "false",
  "lastName": "Doe",
  "locale": "en_GB",
  "mfaMethod": "NONE",
  "uid": "jdoe12",
  "uuid": "eaf993f8-2774-4666-ac7a-ec6c430d3c60",
  "deviceUuid": "e5e171cc-12d2-40bc-ad14-98a98ad3ab47"
}
Response Example (400 Bad Request)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (401 Unauthorized)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}

DELETE /session

User invalidates his current session resulting in a logout.

Returns success if the session is already invalid.

token
in header
string

SSO token of the current user

204 No Content

Session invalidated successfully.

400 Bad Request

Response details:

  • Code : Message
  • Request.Invalid: The request could not be understood by the server due to malformed syntax.
Response Example (400 Bad Request)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}

GET /session/verify

Verifies if the current session is valid. Results in an extension of the session.

token
in header
string

SSO token of the current user

200 OK

Session verified succesfully.

Session gets extended automatically when this call returns 200.

400 Bad Request

Response details:

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

Session is invalid

Session invalidity may be caused by several factors:

  • The session associated with the provided token expired
  • The session associated with the provided token never existed - the token is fake

For security reasons, the real reason for session invalidity is not returned.

Response details

Code Message
Authentication.Unauthenticated Not authenticated. This API is only available for authenticated users.
Response Example (400 Bad Request)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (401 Unauthorized)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}

device

Device APIs allow you to manage your devices. You can do the following (among others):

  • trust / distrust a device
  • get the list of devices you've used

POST /device/trust

Marks current device as Trusted

This service requires the TRUST_CURRENT_DEVICE entitlement.

If SSO session token is provided it is required that token was upgraded through TOTP (authn/totp endpoint)

token
in header
string

SSO token of the current user

Authorization
in header
string

OAuth Access Token of the current user

200 OK

A relation between a user and a device

type
object
400 Bad Request

Request validation error

type
object
401 Unauthorized

Request validation error

type
object
404 Not Found

Device Not Found

type
object
500 Internal Server Error

Internal Server Error

type
object
Response Example (200 OK)
{
  "userId": "53b2f9de-65ae-477a-ae3c-77001b668d40",
  "deviceId": "19e04359-0ae6-4e91-b50f-a8608a382ad7",
  "relationType": "trust",
  "relationValue": "trusted",
  "lastUpdated": "2018-02-13T12:19:11.807"
}
Response Example (400 Bad Request)
{
  "code": "ErrorCode",
  "message": "Some error result",
  "path": "/api/path"
}
Response Example (401 Unauthorized)
{
  "code": "ErrorCode",
  "message": "Some error result",
  "path": "/api/path"
}
Response Example (404 Not Found)
{
  "code": "ErrorCode",
  "message": "Some error result",
  "path": "/api/path"
}
Response Example (500 Internal Server Error)
{
  "timestamp": "Feb 8, 2018 9:00:17 AM",
  "status": 500,
  "error": "Error name",
  "message": "Some error result",
  "path": "/api/path"
}

DELETE /device/trust

Unmarks current device as from Trusted

This service requires the UNTRUST_CURRENT_DEVICE entitlement.

token
in header
string

SSO token of the current user

Authorization
in header
string

OAuth Access Token of the current user

200 OK

OK

400 Bad Request

Request validation error

type
object
401 Unauthorized

Request validation error

type
object
404 Not Found

Device Not Found

type
object
500 Internal Server Error

Internal Server Error

type
object
Response Example (400 Bad Request)
{
  "code": "ErrorCode",
  "message": "Some error result",
  "path": "/api/path"
}
Response Example (401 Unauthorized)
{
  "code": "ErrorCode",
  "message": "Some error result",
  "path": "/api/path"
}
Response Example (404 Not Found)
{
  "code": "ErrorCode",
  "message": "Some error result",
  "path": "/api/path"
}
Response Example (500 Internal Server Error)
{
  "timestamp": "Feb 8, 2018 9:00:17 AM",
  "status": 500,
  "error": "Error name",
  "message": "Some error result",
  "path": "/api/path"
}

GET /user/devices/trust

Gets all devices that user ever marked as Trusted

token
in header
string

SSO token of the current user

Authorization
in header
string

OAuth Access Token of the current user

200 OK

List of Devices

type
object
400 Bad Request

Bad Request

type
object
500 Internal Server Error

Internal Server Error

type
object
Response Example (200 OK)
{
  "devices": [
    {
      "id": "86690e71-cddd-4625-ba7e-ea6f5396f738",
      "uniqueHash": "8d41b93e640932a2398fc639c293fe9aa70d52f72102c27361d4e3d1388f99d6",
      "recoveryHash": "d776b04467ec6736391fbdb5b6962169f82716e8a9fd236f480a37dc5725ba7f",
      "name": "Nexus",
      "salt": "d3928e27-486c-42bd-9aa3-cdad64380aa8",
      "revision": "2",
      "type": "android",
      "properties": "object",
      "history": [
        {
          "type": "android",
          "revision": "1",
          "lastUsed": "2018-02-09T13:55:34.693",
          "properties": "object"
        }
      ],
      "lastUsed": "2018-02-09T13:55:34.693",
      "lastUpdated": "2018-02-09T13:55:34.693",
      "created": "2018-02-09T13:55:34.693"
    }
  ]
}
Response Example (400 Bad Request)
{
  "code": "ErrorCode",
  "message": "Some error result",
  "path": "/api/path"
}
Response Example (500 Internal Server Error)
{
  "timestamp": "Feb 8, 2018 9:00:17 AM",
  "status": 500,
  "error": "Error name",
  "message": "Some error result",
  "path": "/api/path"
}

GET /user/devices/known

Gets all devices that user ever authenticated with successfully

token
in header
string

SSO token of the current user

Authorization
in header
string

OAuth Access Token of the current user

200 OK

List of Devices

type
object
400 Bad Request

Bad Request

type
object
500 Internal Server Error

Internal Server Error

type
object
Response Example (200 OK)
{
  "devices": [
    {
      "id": "86690e71-cddd-4625-ba7e-ea6f5396f738",
      "uniqueHash": "8d41b93e640932a2398fc639c293fe9aa70d52f72102c27361d4e3d1388f99d6",
      "recoveryHash": "d776b04467ec6736391fbdb5b6962169f82716e8a9fd236f480a37dc5725ba7f",
      "name": "Nexus",
      "salt": "d3928e27-486c-42bd-9aa3-cdad64380aa8",
      "revision": "2",
      "type": "android",
      "properties": "object",
      "history": [
        {
          "type": "android",
          "revision": "1",
          "lastUsed": "2018-02-09T13:55:34.693",
          "properties": "object"
        }
      ],
      "lastUsed": "2018-02-09T13:55:34.693",
      "lastUpdated": "2018-02-09T13:55:34.693",
      "created": "2018-02-09T13:55:34.693"
    }
  ]
}
Response Example (400 Bad Request)
{
  "code": "ErrorCode",
  "message": "Some error result",
  "path": "/api/path"
}
Response Example (500 Internal Server Error)
{
  "timestamp": "Feb 8, 2018 9:00:17 AM",
  "status": 500,
  "error": "Error name",
  "message": "Some error result",
  "path": "/api/path"
}

policy

Policy APIs allow you to validate access policies based on their configurations.

POST /policy/{policyName}/application/{applicationId}/validate

Validate application policy by name

token
in header
string

SSO token of the current user

Authorization
in header
string

OAuth Access Token of the current user

policyName
in path
string

(no description)

applicationId
in path
string

(no description)

202 Accepted
  • Policy has been validated successfully
400 Bad Request
  • AuthorizationPolicy.InvalidBody: Invalid request body * AuthorizationPolicy.CouldNotValidateValidator: Could not validate validator
403 Forbidden
  • AuthorizationPolicy.Unauthorized: Unauthorized
404 Not Found
  • AuthorizationPolicy.NotFound: Policy not found
500 Internal Server Error
  • AuthorizationPolicy.CouldNotGetContext: Could not get context
  • AuthorizationPolicy.CouldNotGetValidators: Could not get validators
Response Example (400 Bad Request)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (403 Forbidden)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (404 Not Found)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (500 Internal Server Error)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}

kba

Knowledge-based authentication APIs allow you to retrieve information about KBA configuration.

kba

GET /config/kba

Returns the default system KBA configuration.

200 OK

KBA configuration was retrieved.

400 Bad Request

Response details:

  • Code : Message
  • Request.Invalid: The request could not be understood by the server due to malformed syntax.
404 Not Found

Response details:

  • Code : Message
  • KbaConfig.NotFound: The KBA config does not exist.
Response Example (200 OK)
{
  "kbaConfigId": "default",
  "kbaQuestionSet": [
    {
      "questionIdentifier": "msq0",
      "questionPhrase": "What is my favorite sport?"
    },
    {
      "questionIdentifier": "msq1",
      "questionPhrase": "What is my favorite food?"
    }
  ],
  "kbaMinQuestionsPerUser": 2,
  "kbaMaxQuestionsPerUser": 4
}
Response Example (400 Bad Request)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}
Response Example (404 Not Found)
{
  "code": "someErrorCode",
  "message": "errorMessage",
  "details": {
    "additionalFields": "additionalInformation"
  }
}

oauth

Oauth APIs expose a set of Oauth RFC APIs

GET /oauth/authorize

Authenticate user using OAuth 2.0 standard.

User will be redirected to provider's login page.

For more details please find RFC: https://tools.ietf.org/html/rfc6749#section-3.1

response_type
in path
string

Response type

  • code -> server side flow
  • token -> client side flow
client_id
in path
string

OAuth Client Id

redirect_uri
in query
string

Client's redirection endpoint

scope
in query
string

The scope of the access request

state
in query
string

An opaque value used by the client to maintain state between the request and callback

302 Found

Redirection to provider's login page

POST /oauth/introspect

Returns meta information surrounding the token, including whether this token is currently active.

For more details please find RFC: https://tools.ietf.org/html/rfc7662#section-2

token
in formData
string

The string value of the token

token_type_hint
in formData
string

A hint about the type of the token submitted for introspection

200 OK

Meta information about token

type
object
401 Unauthorized

Invalid credentials

Response Content-Types: application/json
Response Example (200 OK)
{
  "active": true,
  "client_id": "l238j323ds-23ij4",
  "username": "jdoe",
  "scope": "read write dolphin",
  "sub": "Z5O3upPC88QrAjx00dis",
  "aud": "https://protected.example.net/resource",
  "iss": "https://server.example.com/",
  "exp": 1419356238,
  "iat": 1419350238,
  "extension_field": "twenty-seven"
}

POST /oauth/revoke

Revokes token or ignores request if token is not valid

For more details please find RFC: https://tools.ietf.org/html/rfc7009#section-2

token
in formData
string

The string value of the token

token_type_hint
in formData
string

A hint about the type of the token submitted for introspection

200 OK

Done

400 Bad Request

OAuth Error

type
object
Response Content-Types: application/json
Response Example (400 Bad Request)
{
  "error": "invalid_request",
  "error_description": "missing parameter",
  "error_uri": "http://uri-to-error-description"
}

POST /oauth/token

Obtain an access token by presenting its authorization grant or refresh token

For more details please find RFC: https://tools.ietf.org/html/rfc6749#section-3.2 and https://tools.ietf.org/html/rfc6749#section-4.1.3

grant_type
in formData
string

Value MUST be set to "authorization_code"

code
in formData
string

The authorization code received from the authorization server

redirect_uri
in query
string

Client's redirection endpoint

client_id
in query
string

OAuth Client Id

200 OK

Access Token

type
object
400 Bad Request

OAuth Error

type
object
Response Content-Types: application/json
Response Example (200 OK)
{
  "access_token": "2YotnFZFEjr1zCsicMWpAA",
  "token_type": "example",
  "expires_in": 3600,
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
  "example_parameter": "example_value"
}
Response Example (400 Bad Request)
{
  "error": "invalid_request",
  "error_description": "missing parameter",
  "error_uri": "http://uri-to-error-description"
}

openid

OpenId APIs expose a UserInfo endpoint compliant with OpenId Connect specification.

GET /oauth/userinfo

OAuth 2.0 Protected Resource that returns Claims about the authenticated End-User.

For more details please find: http://openid.net/specs/openid-connect-core-1_0.html#UserInfo

Authorization
in header
string

Access Token

200 OK

User Info

type
object
401 Unauthorized

Unauthorized

Response Content-Types: application/json
Response Example (200 OK)
{
  "sub": 248289761001,
  "example_parameter": "example_value"
}