Cloud Administration Live Verification APIs
8 months ago

Cloud Administration Live Verification APIs

The Live Verification APIs enable you to securely verify a user's identity in real time using any registered multi-factor authentication (MFA) method. These APIs support the end-to-end verification process during help desk support interactions, including initiating a verification request, checking its status, validating a user’s verification code, or canceling the session if needed.

Note:  These APIs are licensed. See ID Plus Subscription Plans.

For information about managing access to this API, see Accessing the Cloud Administration APIs.

Authentication

Clients calling these APIs must authenticate themselves by including an OAuth token in a request. For information on using this token, see Manage OAuth API Clients.

Software Developer Kit

You can download the API Software Developer Kit (SDK) from Cloud Administration REST API Download.

Start Verify API

The Start Verify API initiates a Live Verification session by triggering an MFA prompt to the user’s registered device. You can use it during support calls to confirm a user's identity before making changes like updating profile details or adding a new device.

Note:  Only customers with an active Live Verification license can use the Start Verify API.

Request Requirements

Use the following information to start the live verification process for a user.

MethodRequest URLResponse Codes
POST /AdminInterface/restapi/v1/users/ < userId >/verify/start

200, 400, 403, 404, 409, 500

Request Parameter

Use the following request parameter.

Request ParameterDescriptionData Type
<userId>Unique user identifier in uuid format

String

Request Body

No request body is required.

Example Request Data

The following example displays a request.

POST /AdminInterface/restapi/v1/users/021c6ea5-5b27-c0e1-c04f-886bd0416e5a/verify/start

Content-Type: application/json

Authorization: Bearer <Oauth token>

Example Response Body

The following example displays a response body. 

{

    "userId": "021c6ea5-5b27-c0e1-c04f-886bd0416e5a",

    "userEmail": " example@rsavia.com",

    "adminUsername": "admin@rsavia.com ",

    "sessionExpiration": "2025-02-25T19:10:30.045Z"

    "verifyUrl": "https://mycompany.auth-dev.securid.com/verify"

}

Response Property Descriptions

The following table shows property descriptions and data types.

PropertyDescriptionData Type
adminUsernameAdministrator who initiated verify session. String
sessionExpirationExpiration date of the verify session. See https://www.w3.org/TR/NOTE-datetime for information on formatting timestamps in ISO 8601 format.String
userEmailuser email String
userId user uuidString
verifyUrlThe verification urlString

 

Response Codes

The following table shows response codes for this API.

CodeDescription
200Successfully started the verification for the end user.
400

The operation was not performed. One of the following messages may be returned:

  • Missing or invalid user identifier.

  • User is disabled.

  • Live Verification policy does not exist or is not enabled.

403

Not authorized to perform the request.

When the customer is not entitled to use this feature, the system returns HTTP 403.

404User does not exist. The following error message is returned: User <userId> not found.
409

Session is already in progress by another admin. The following error message is returned: User has a verification session going on already.

429Too many requests.
500

Internal server error occurred when processing the request, or an unexpected error occurred. One of the following error messages may be returned:

  • An internal error occurred.

  • Failed to complete service call to: Start user verification.

 

Status API

The Status API retrieves the current state of an active Live Verify session.

Request Requirements

Use the following information to check the status of a verification request the live verification process for a user.

MethodRequest URLResponse Codes
GET/AdminInterface/restapi/v1/users/ < userId >/verify/status

200, 400, 403, 500

 

Request Parameter

Use the following request parameter.

Request ParameterDescriptionData Type
<userId>Unique user identifier in uuid format String

 

Response Body

The following example displays a response body. 

{
    "status": "STARTED",
    "sessionExpiration": "2025-02-25T19:10:30.045Z",
    "adminUsername": "admin@rsavia.com"
}

Response Property Descriptions

The following table shows property descriptions and data types.

PropertyDescriptionData Type
adminUsername The administrator who initiated the live verification session. String
status

Status of the ongoing live verification session. Can be one of the following:

  • STARTED - The live verify session has started.

  • CODE_GENERATED - The user verified the policy challenge, and the verification code is now generated.

  • NO_SESSION - There is no live verify session in progress.

String
sessionExpiration Expiration date of the live verification session. See https://www.w3.org/TR/NOTE-datetime
for information on formatting timestamps in ISO 8601 format.		String

 

Response Codes

The following table shows response codes for this API.

CodeDescription
200Successfully returned the started verification status back.
400

The operation was not performed. One of the following messages may be returned: Missing or invalid user identifier

403Not authorized to perform the request.
500Internal server error occurred when processing the request, or an unexpected error occurred.

 

Validate API 

The Validate API confirms whether the verification code entered by the user is correct for the current Live Verify session. You can use it to complete the identity verification process after the user responds to the MFA prompt.

Request Requirements

Use the following information to validate the live verification code for a user.

MethodRequest URLResponse Codes
POST/AdminInterface/restapi/v1/users/ < userId >/verify/code

200, 400, 403, 404, 409, 500

 

Request Parameter

Use the following request parameter.

Request ParameterDescriptionData Type
<userId>Unique user identifier in uuid formatString

 

Request Body

Request BodyDescriptionData Type
{ "verifyCode": "<code>" }JSON carrying verifyCode JSON String

 

Response Body

The following example displays a response body. 

{
    "verifyStatus": "SUCCESSFUL_CODE_VERIFICATION | FAILED_CODE_VERIFICATION",
    "adminUsername": "<email of the admin who started the session>"
}

Response Codes

The following table shows response codes and descriptions for API.

CodeDescription
200Successfully completed the validation of the verify code for the end user. The response body will tell you whether or not the verification was successful or failed.
400

The operation was not performed. One of the following messages may be returned:

  • Missing or invalid user identifier.

  • User is disabled.

  • Live Verification policy does not exist or not enabled.

403Not authorized to perform the request.
404

User does not exist. One of the following messages may be returned:

  • User <userId> not found.

  • Session not found for given user identifier.

409Session is already in progress by another administrator. The following error message is returned: User has a verification session going on already.
500Internal server error occurred when processing the request, or an unexpected error occurred.

 

Cancel API

The Cancel API cancels a Live Verify session that is in progress. Use it to end the session if it is no longer required.

Request Requirements

Use the following information to cancel the live verification process for a user.

MethodRequest URLResponse Codes
POST/AdminInterface/restapi/v1/users/ < userId >/verify/cancel

200, 400, 403, 404, 409, 500

Request Parameters

Use the following request parameter.

Request ParameterDescriptionData Type
<userId>Unique user identifier in uuid formatString

Request Body

No request body is required.

Response Body

No response body is required.

Response Codes

The following table shows response codes for this API.

CodeDescription
200Successfully cancelled the verification for the end user.
400

The operation was not performed. One of the following messages is returned: Missing or invalid user identifier.

403Not authorized to perform the request.
404Live verify session does not exist.
409Session is already in progress by another admin, so the session was not cancelled. Only the admin who created the Live verify session can cancel that session.
500Internal server error occurred when processing the request, or an unexpected error occurred.

 

Live Verification API Error Messages

The following table lists possible error messages returned by the Live Verification APIs, along with their descriptions.

Error Message
ERRORAn error occurred.
POLICY_NOT_ENABLED Live Verification policy is not enabled or has not been published.
INVALID_USER_ID Missing or invalid user identifier.
USER_NOT_FOUND User not found.
USER_NOT_FOUND User is disabled.
SESSION_NOT_FOUND Session not found.
Don't see what you're looking for?