Skip to main content

Request recovery codes

Providing recovery codes for your users enables a fallback authentication method in case they lose or damage their mobile phone. Recovery codes are sets of static 16-digit, alphanumeric, case-sensitive codes. Each can be used once for emergency authentication.

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

Send an HTTP request to the registration endpoint​

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

Send the POST https://{instance}.mauth.nevis.cloud/api/v1/users/enroll call with your instance ID, and 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 the username and recovery_username parameters. Both are the username of the user who requires emergency authentication.

    Use unique static information for the username parameter. To link a user to your internal systems, you might use, for example, an internal customer ID or employee ID, and provide that as a username in the user registration request. It is important to use information that does not change over the life cycle of a user.

    Do not use a username with any Personally Identifiable Information (PII). For example, an email address is not recommended because it is not only PII data, but it also might change over the lifecycle of a user.

    Preventing User Impersonation

    To prevent impersonation, ensure you only link users to your backend records after strongly authenticating them first.

HTTP request example​

cURL code sample requesting recovery codes
curl -v -X POST https://$instance.mauth.nevis.cloud/api/v1/users/enroll \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $access_key" \
-d "{ \"username\":\"$recovery_username\",
        \"channel\":\"recovery\"
    }"

HTTP response example​

A set of sixteen recovery codes is returned as part of the registration data. Each code can be used only once. If a new batch is requested, all previous codes become invalid.

{
    "authenticators": [],
    "createdAt": "2021-07-05T07:57:12.184902Z",
    "enrollment": {
        "recoveryCodes": [
            "3YL2-...-PnZh",
            "4B90-...-fgF2",
            ...
            "YTbB-...-lCI0"
        ],
        "transactionId": "bec412cc-...-d2cb24bac64b"
    },
    "phones": [],
    "recoveryCodes": null,
    "status": "new",
    "updatedAt": "2021-07-05T07:57:12.184904Z",
    "userId": "2eda9f3c-...-a897e3bf0b7c",
    "username": "testUser20210702C"
}

Display recovery codes​

The recovery codes are returned in the registration response in the enrollment.recoveryCodes field. Once received, ensure that you display the recovery codes on your frontend, and notify the user to save the codes. The user will not be able to see the codes later.