Regenerate recovery codes

POST

/v1/mfa/recovery-codes

curl --request POST \
  --url https://api.aetherpush.com/v1/mfa/recovery-codes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "stepUp": { "type": "passkey", "response": {}, "code": "example" } }'

• Production
• Staging
• Local development

Session-only. Replaces all existing recovery codes with a fresh set, returned exactly once. Requires MFA to be enabled and a fresh step-up proof of an existing factor.

Authorizations

• accessKeyAuth

Request Body

Media typeapplication/json

object

stepUp

Fresh proof of a second factor the account already holds, required to change the factor set once MFA is enabled. A stolen session cannot enrol its own factor and then strip the owner’s. Recovery codes and passwords are deliberately not accepted here: a recovery code recovers a login but never authorizes a factor change.

object

type

required

string

Allowed values: passkey totp

response

WebAuthn AuthenticationResponseJSON. Required when type is passkey.

object

key

additional properties

any

code

A current authenticator code. Required when type is totp.

string

Responses

201

New recovery codes, shown exactly once.

Media typeapplication/json

object

recoveryCodes

required

Shown exactly once; the server stores only hashes.

Array<string>

Example^generated

{
  "recoveryCodes": [
    "example"
  ]
}

400

MFA is not enabled for this account.

Media typeapplication/json

object

error

required

Human-readable error message.

string

requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string

Example

{
  "error": "The requested resource was not found.",
  "requestId": "req_abc123"
}

401

Authentication required, or step-up is required and not satisfied (code: step_up_required).

Media typeapplication/json

One of:

object

object

error

required

Human-readable error message.

string

requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string

object

Returned when a factor-set change on an MFA-enabled account arrives without a fresh step-up proof. Same shape as the reauth response so clients branch on code and open the step-up flow, not on message text.

object

error

required

string

code

required

string

Allowed values: step_up_required

requestId

string

Example

{
  "error": "The requested resource was not found.",
  "requestId": "req_abc123"
}

403

API keys and named access keys cannot manage recovery codes; a login session is required.

Media typeapplication/json

object

error

required

Human-readable error message.

string

requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string

Example

{
  "error": "The requested resource was not found.",
  "requestId": "req_abc123"
}