1. Docs
  2. API Reference
  3. Prove a fresh factor to authorise a sensitive MFA mutation

Prove a fresh factor to authorise a sensitive MFA mutation

POST/v1/identity/auth/mfa/step-up

Authentication

  • Bearer Token Authorization

    JWT access token

Request body

  • factorenum: "totp" | "recovery_code"*

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

  • codestring*

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

Code samples

cURLJavaScriptPythonGo
curl -X POST "https://api.canopy.dev/v1/identity/auth/mfa/step-up" \
  -H "Authorization: Bearer $CANOPY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "factor": "totp",
    "code": "string"
  }'

Responses

200 Verifies a TOTP code or single-use recovery code from the caller's enrolled factors and returns a short-lived (5 min) sealed `step_up_token` that DELETE /mfa/factors/:id and POST /mfa/recovery-codes/regenerate consume via the X-Mfa-Step-Up-Token header. On failure, the 401 response body's `error.code` is `mfa.step_up_invalid` (factor verification failed) or `auth.invalid_token` (caller's bearer token is invalid).
{
  "step_up_token": "string",
  "expires_at": "2026-04-20T12:00:00.000Z"
}

application/json

  • step_up_tokenstring*

    Opaque sealed token (AES-256-GCM, base64url). Pass back on the next mutation via the `X-Mfa-Step-Up-Token` header. Valid for 5 minutes.

  • expires_atstring (date-time)*

    After this timestamp the token is rejected and the caller must POST /mfa/step-up again.

401 Invalid or expired token
403 This token is not authorized for this endpoint (wrong principal type — e.g., admin token on identity-only endpoint, or vice versa)

Returned object

On this page

Related endpoints

GETList enrolled MFA factors for the caller
POSTBegin TOTP factor enrollment
POSTComplete TOTP factor enrollment
POSTBegin WebAuthn factor enrollment
POSTComplete WebAuthn factor enrollment
POSTBegin a WebAuthn-backed step-up ceremony
POSTComplete a WebAuthn step-up ceremony
DELETERemove an enrolled MFA factor
POSTRegenerate the identity's single-use recovery codes
GETList the identity's active 'remember this device' records
DELETERevoke every trusted device for the caller
DELETERevoke a single trusted device