---
title: "Generate the user's one-time set of MFA recovery codes."
method: POST
path: "/factors/recovery-codes"
tags: ["user"]
---

# Generate the user's one-time set of MFA recovery codes.

`POST /factors/recovery-codes`

## Request

- Base URL: `https://abcdefghijklmnopqrst.supabase.co/auth/v1`
- URL: `https://abcdefghijklmnopqrst.supabase.co/auth/v1/factors/recovery-codes`
- Auth: API key in header `apikey` and HTTP bearer

Creates a verified `recovery_code` factor together with a set of single-use codes. The plaintext codes are returned exactly once, in canonical form. Requires an AAL2 session and at least one other verified factor, because recovery codes can never be the user's only second factor. Use `POST /factors/recovery-codes/regenerate` to rotate an existing set.

## Request body

- object
  - `friendly_name` string: Name shown in the user's factor list. Subject to the same per-user uniqueness rule as any other factor. Defaults to `Recovery codes` when omitted or blank.

## Response `200`

Recovery codes were generated. Show the `codes` to the user now; they cannot be retrieved again.

- MFARecoveryCodesSchema: A freshly generated set of MFA recovery codes. Returned only by `POST /factors/recovery-codes` and `POST /factors/recovery-codes/regenerate`; the codes cannot be retrieved afterwards.
  - `id` string, uuid: ID of the user's `recovery_code` factor.
  - `type` string: Always `recovery_code`.
  - `friendly_name` string
  - `total` integer: Number of codes in the set.
  - `codes` string[]: The plaintext single-use codes in canonical form (16 characters by default). Show them to the user once.

## Other responses

- `400`: HTTP Bad Request response. Can occur if the passed in JSON cannot be unmarshalled properly or when CAPTCHA verification was not successful. In certain cases can also occur when features are disabled on the server (e.g. sign ups). It may also mean that the operation failed due to some constraint not being met (such a user already exists for example).
- `403`: Forbidden error. Requires an AAL2 session; anonymous users cannot use recovery codes.
- `422`: Unprocessable entity. Recovery-code enrollment is disabled on the server, the user has no other verified factor, recovery codes are already enrolled (use `POST /factors/recovery-codes/regenerate`), the friendly name is already used by another factor, or the user has reached the maximum number of enrolled or verified factors.

## Changes

- **2026-09-21** `2e2206095d36`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/supabase/apis/supabase-auth-rest-api/changes/factors/recovery-codes/post.md)

---

[API](https://skmtc.dev/supabase/apis/supabase-auth-rest-api.md) - [All operations](https://skmtc.dev/supabase/apis/supabase-auth-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/supabase/apis/supabase-auth-rest-api/revisions/c480c2703e65?raw)