Cloudentity User Service API

Returns the default system KBA configuration.

Activates developer account for current user (self service). This service grants the SELF_MANAGE_APPLICATIONS entitlement. Returns success if the SELF_MANAGE_APPLICATIONS is already granted to a user.

Returns the default system KBA configuration.

Activates developer account for current user (self service). This service grants the SELF_MANAGE_APPLICATIONS entitlement. Returns success if the SELF_MANAGE_APPLICATIONS is already granted to a user.

Get a user’s record from the user store using HMAC authentication.

The ADMIN_GET_SESSION_USER_VIA_HMAC entitlement is required.

This API uses the same request authorization headers as POST /apiKey/entitlement/validate (Validate Entitlements using API Key). See documentation for that API for details about authorization header inputs.

Internal API to get a user’s record from the user store using HMAC or JWT authentication.

For HMAC, the ADMIN_GET_USER_VIA_HMAC entitlement is required.

For JWT, valid jwt is required without specified payload.

Unlike the ordinary Get User API, the users visible through this API are not constrained to the current session customer.

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 no customer CID is supplied, the user will be registered under the default customer. 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.

Get the current user’s record.

The current user is identified by the session token.

This service requires the SELF_GET_USER entitlement.

Update the current user’s record.

The current user is identified by the session 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.

Confirm password reset using received code.

Upon success, the user is activated.

If the activation code corresponds to an MFA user who has confirmed his or her googleAuthSecret, then a valid Google Authentication pin (googlekey) is required. For such a user, if no googlekey is supplied or its value is incorrect, an Authentication.InvalidMFA error will be returned.

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

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 deliveryMode is specified, the message is sent to the user’s first unverified email ('E') or mobile ('M' or 'V') - If neither is specified, the message is sent to the user’s first unverified email or mobile based on the user’s otpMethod - If neither is 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 - The destination type resolves to email or mobile but the user has no unverified address of that type

Generates and sends a one-time password ("OTP") to the authenticated user’s verified or identifier email (via SMTP) or mobile (via SMS).

The destination address is based on the destination and deliveryMode request parameters, as well as the user’s existing verified emails and mobiles, and the otpMethod and otpMfaDestination attributes: - If destination and deliveryMode are specified and corresponds to one of the user’s verified or identifier emails or mobiles, the OTP is sent to this destination according to the specified deliveryMode. - If maskIdentifierKey and deliveryMode are specified, the OTP is sent to the resolved destination according to the specified deliveryMode. The "Get Masked Identifiers" API must have been called prior to using this mode; the maskIdentifierKey references one of the identifier references returned by that API. - If neither is specified, the OTP is sent to the user’s otpMfaDestination, according to the delivery mode in the user’s otpMethod.

If the destination or maskIdentifierKey parameters are specified but the user has no corresponding verified or identifier email or mobile, a User.AddressNotFound error will be returned.

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

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.

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.

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.

Get the current user’s devices.

This service requires the SELF_LIST_DEVICES entitlement.

The user accepts the EULA (End User License Agreement) to gain access to the website. This api invalidates all sessions of a user excluding current session.

The SELF_ACCEPT_USER_EULA entitlement is required.

The following user attributes are set automatically - eulaApproval = true - eulaRevision = customer.eulaRevision

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.

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.

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.

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

The user is identified by the session token provided.

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.

If the supplied OTP code is incorrect, an Authentication.InvalidCredentials error will be generated.

If the supplied code is in the form of an encrypted code (used in other APIS), a Request.Invalid error will be generated.

A Request.Gone error may be generated by any of the following conditions: - No OTP has been generated for this user - The OTP has expired - The OTP has been removed because the maximum number of failed attempts has been exceeded

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. A Request.Invalid error may be generated by any of the following conditions:

If configuration attribute withSession is true and body parameter issueSession is true, API will return a session token

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.

Returns an obfuscated view of a user’s verified and unverified emails and mobiles.

For each masked identifier, a randomly generated key is returned. This string may be used to reference the corresponding email or mobile as a destination, for requests to various "sending" APIs.

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.

Allows a user to set or change his or her KBA responses. Responses are case-insensitive.

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.

Upon success, the user’s response answers are hashed and stored.

A user’s KBA response set may be changed by simply supplying a new, complete set of KBA responses.

This service requires the SELF_SET_USER_KBA_RESPONSES entitlement.

Generates and returns a new set of KBA challenge questions for the user identified by the provided session token.

The selected set of questions is a subset of the questions to which a user has supplied responses during KBA setup. If the central KBA config allows a user to respond to more more questions than the minimum required, the minimum number will be randomly chosen from among the user’s responses; in this case, this API must be called prior to each KBA authentication. Otherwise, the challenge set will be equal to the full set of questions to which the user has supplied responses.

If a challenge set has already been generated for this user without a successful authentication, subsequent calls to this API will return the same set of questions; this forces a user to respond correctly to any pending challenge.

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

No entitlement is required to call this API.

Verifies an encrypted code or one-time password (OTP) to faciliate an MFA-reset flow. Upon success a session token is returned.

If the request code param is a plaintext OTP, the identifier and mfaMethod params must also be supplied in order to identify the user and MFA type.

If the email destination was unverified, the new session’s authenticationIdentifier will be set to the first available identifier of the user: uid, identifierEmail, identifierMobile.

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.

If the provided code does not correspond to an allowable OTP action type for this API (e.g. a code intended for user activation was provided), an Authentication.InvalidMFA error will be returned.

Allows a user to set his or her MFA method.

The MFA method must be chosen among the following values: - NONE - GOOGLE_AUTHENTICATION - OTP - KBA - DUO_AUTHN

This service requires the SELF_SET_MFA_METHOD entitlement.

Changes a user’s otpMfaDestination and otpMethod.

The user must have completed MFA enrollment to make this request. The provided OTP code must be plain text and have been generated from the Send Verification Code API. The provided destination must be one of this user’s unverified/verified addresses. The provided otpMethod is allowable in combinations with destination if it is: - an email address: E (SMTP) - a mobile address: M (SMS) or V (VOICE)

Upon success, the otpMfaDestination and otpMethod are changed.

If the provided address is an email and no defaultEmail is set, it is promoted to defaultEmail. If it was a mobile and no defaultMobile is set, then it becomes defaultMobile.

If the address was unverified, it will be upgraded from unverified to verified, but no change occurs if the address was already verified.

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.

A Request.Gone error may be generated by any of the following conditions: - The verification code has expired - The OTP was generated from other action. - The verification code has been removed because the maximum number of failed attempts has been exceeded

An Authorization.Unauthorized error may be generated if this API was somehow triggered by a user who has not completed MFA setup.

A Request.Invalid error may be generated if: - The provided OTP MFA Change destination did not match the identifier issued by the OTP code.

A User.OtpDeliveryModeInvalid error may be generated if: - The otpMethod is not among the allowable combinations described above.

A User.NotFound error may be generated if the OTP generated address is not included in user data.

Confirms a user’s email or mobile based on a one-time password (OTP) sent to the address.

The provided OTP code must have been generated and matched with the user’s otpMfaDestination.

Upon success, the otpSetupComplete flag is set to true.

If the address is an email and no defaultEmail is set, it is promoted to defaultEmail. If it was a mobile and no defaultMobile is set, then it becomes defaultMobile.

If the address was unverified, it will be upgraded from unverified to verified, but no change occurs if the address was already verified.

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.

A Request.Gone error may be generated by any of the following conditions: - The verification code has expired - The OTP was generated from other action. - The verification code has been removed because the maximum number of failed attempts has been exceeded

A Request.Invalid error may be generated if otpMfaDestination was not set or not matched with provided OTP address.

A User.NotFound error may be generated if the address to which the OTP had been sent is not included in user data.

Begins OTP authentication setup process for a user.

This API operates in three modes, based on attributes present in the request: - Mode 1: destination, destinationType and otpMethod are required. Upon success, the user’s OTP destination and method attributes are set. An OTP is sent to the requested destination, according to the otpMethod requested. If the destination does not already exist among the user’s addresses, it will be added to the user’s unverified emails or mobiles, according to the destinationType requested. - Mode 2: otpMethod and maskIdentifierKey are required. The "Get Masked Identifiers" API must have been called prior to using this mode; the maskIdentifierKey references one of the identifier references returned by that API. An OTP is generated and sent to the referenced destination, according to the otpMethod requested. If the requested key does not match any stored destination, an Address.NotFound error is returned. - Mode 3: No inputs are allowed. An OTP is generated and sent to the user’s stored OTP destination, according to the stored otpMethod. If no OTP destination and method are found, a Request.Invalid error is returned with details identifying the missing attribute.

In all cases, upon success any previously set otpSetupComplete flag is set to false.

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

This service requires the SELF_CHANGE_PASSWORD entitlement.

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

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.

Set the user’s customer for the current user session (session.customer).

This service requires the SELF_UPDATE_USER_CUSTOMER_IN_SESSION entitlement.

The specified customer must be in the customers list associated with this user, unless the ADMIN_ALL_CUSTOMERS entitlement is owned.

Process Outline - If user does not have the SELF_UPDATE_USER_CUSTOMER_IN_SESSION entitlement - Return Authorization.Unauthorized - If the user does not have the ADMIN_ALL_CUSTOMERS entitlement - Get the user record.customers - If the requested customer is not in the record.customers list - Return Authorization.Unauthorized - Replace the user session.customer attribute with the requested customer

Changes a user’s UID. If successful, the user’s sessions will be invalidated.

The UID may not be email or mobile formatted; otherwise, a User.ValidationError will be returned.

If the provided UID already exists among this or another user’s identifiers, a User.Duplicate error will be returned.

This service requires the SELF_CHANGE_UID entitlement.