1. Docs
  2. API Reference
  3. Prove a fresh second factor before a sensitive change

Prove a fresh second factor before a sensitive change

POST/v1/auth/mfa/step-up

Performs an in-session step-up for the authenticated administrator by verifying a totp or recovery_code factor against their own enrolled factors, returning a sealed five-minute step_up_token that authorizes removing a factor, regenerating recovery codes or changing the email address. A recovery code used here is consumed. Distinct from the sign-in challenge: the caller already holds a session. Responds 401 (mfa.step_up_invalid) for a wrong code, and audits it. Rate-limited to 10 requests per minute.

Authentication

Bearer TokenAuthorization

JWT access token. Never send alongside X-API-Key: a request carrying both is refused.

Request body

application/json

factorenum Required

The factor type the caller is satisfying. WebAuthn step-up lands once WebAuthn factors are enrollable.

one of "totp" · "recovery_code"

codestring Required

A 6-digit TOTP code or a single-use recovery code (case + dash insensitive).

Responses

application/json

  • dataMfaStepUpResponseDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

Rate limit

10 requests per 1mPer caller: the signed-in user for a bearer token; for an API key, the key and the end user's address when a backend forwards it, otherwise the client address

Returned object

MfaStepUpResponseDtoView all properties on this resource
Request
curl -X POST "https://auth.canopy-io.com/v1/auth/mfa/step-up" \
  -H "Authorization: Bearer $CANOPY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "factor": "totp",
    "code": "string"
  }'
Response
{
  "data": {
    "step_up_token": "string",
    "expires_at": "2026-04-20T12:00:00.000Z"
  }
}
 Related endpoints
GETList the caller's enrolled second factors
POSTBegin authenticator app enrollment
POSTComplete authenticator app enrollment
POSTBegin passkey enrollment
POSTComplete passkey enrollment
POSTBegin a passkey step-up
POSTComplete a passkey step-up
DELETERemove one of the caller's second factors
GETHow many recovery codes the caller has left
POSTRegenerate the caller's recovery codes
GETList the caller's remembered devices
DELETEForget every remembered device
DELETEForget one remembered device
 Was this page helpful?

Tell us how we can improve this guide.

Canopy