Generate Recovery Codes

This API is used to generate a list of Recovery Codes. When creating new codes, any existing Recovery Codes will be cleared and the new set will become the current values.

Request#

Create Recovery Codes

POST/api/user/two-factor/recovery-code/{userId}

OpenAPI Spec

Request Parameters#

userIdUUIDrequired

The unique Id of the user to assign the generated Recovery Codes to.

Response#

The response for this API contains an array of Recovery Codes that were created. In both standard and FIPS modes, 10 codes are returned. In standard mode, codes use the format XXXXX-XXXXX. In FIPS mode, codes use the format XXXXXXX-XXXXXXX.

The returned codes are the only time they are available in plaintext — they are hashed at rest and cannot be retrieved afterward. Store them securely and provide them to the user immediately. Since 1.68.0.

Response Codes

Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

Response Body#

recoveryCodesArray<String>

The array of Recovery Codes.

Example Response JSON

{
  "code": "752185",
  "recoveryCodes": [
    "QJD73-L6GR5",
    "R7RJH-GB7H3",
    "JJ5YZ-KS4C3",
    "CRDHP-7L355",
    "928QS-P9HMJ",
    "8VLFT-Z2WMM",
    "PQZX9-YV5VR",
    "TK9TB-7BT6H",
    "6QYPL-ZPQJV",
    "VJ35W-98RW4"
  ]
}