Skip to main content

Authenticate transactions with recovery codes

As a fall-back recovery mechanism, users can use any of their previously generated recovery codes to authenticate a transaction. To generate a set of recovery codes, see Request recovery codes.

The following diagram shows the end-to-end sequence of an authentication operation with a recovery code. The steps that must be performed to integrate the Authentication Cloud into your application are in bold.

Prompt user to enter a recovery code​

Ensure that you create a prompt in your frontend for the user to enter one of their recovery codes. After the user provides the code, you must verify it with an HTTP request to the verification endpoint.

Send an HTTP request to the verification endpoint​

For detailed information on the HTTP request parameters and response fields, see the Verification endpoint page of the API reference documentation.

Send the POST https://{instance}.mauth.nevis.cloud/api/v1/users/{userId}/verification call with your instance ID the userId of the given user. The userId must be the ID of the recovery_username you previously set when requesting the recovery codes. Configure the HTTP request as follows:

  1. Send your access key or intent token in the Authorization Bearer token header. For more information on the intent token, see Intent endpoint.
  2. Set the channel parameter to recovery.
  3. Set your code variable.

After the verification request is sent, Authentication Cloud checks whether the user is rate limited. If the user is rate limited, the the authentication operation fails.

HTTP request example​

curl -v https://$instance.mauth.nevis.cloud/api/v1/users/$userId/verification \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $access_key" \
    -d "{ \"code\":\"$code\",
          \"channel\":\"recovery\" }"

HTTP response example​

HTTP/1.1 200 OK

The response is either an HTTP/1.1 200 if the verification is successful, or an HTTP/1.1 4xx otherwise.