1. Docs
  2. API Reference
  3. OAuth hosted login: acknowledge recovery codes

OAuth hosted login: acknowledge recovery codes

POST/oauth/mfa-enroll-codes-ack

Final step of hosted MFA enrollment: the person confirms they saved their recovery codes. Validates the sealed ack_token (state verified, matching client_id). Without acknowledged=true it mints nothing and shows the same codes again, from the sealed codes_token the page carried, with the reason. With it, mints the authorization code (stamping the OIDC amr from the enrolled factor) and redirects to the client's redirect_uri. Renders an expired-session page when a token is invalid. Works without JavaScript. Throttled to 10 requests per minute.

Request body

application/json

ack_tokenstring Required
client_idstring Required
redirect_uristring Required
response_typestring Required
scopestring Required
statestring Optional
code_challengestring Required
code_challenge_methodstring Required
noncestring Optional
codes_tokenstring Required

The recovery codes as the page received them, sealed. Opaque to the browser.

acknowledgedstring Optional

Present and `true` when the person ticked "I've saved my recovery codes". Absent or anything else shows the codes again with the reason; no code is minted.

Responses

text/html

string

A redirect to the client's `redirect_uri` with `code` and `state` once the sign-in clears

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
Request
curl -X POST "https://auth.canopy-io.com/oauth/mfa-enroll-codes-ack" \
  -H "Content-Type: application/json" \
  -d '{
    "ack_token": "string",
    "client_id": "string",
    "redirect_uri": "string",
    "response_type": "string",
    "scope": "string",
    "state": "string",
    "code_challenge": "string",
    "code_challenge_method": "string",
    "nonce": "string",
    "codes_token": "string",
    "acknowledged": "string"
  }'
Response
Content-Type: text/html

<!doctype html>
<html lang="en">
  <head>…</head>
  <body>
    <!-- The hosted page: its form, any error, and the Environment's branding -->
  </body>
</html>
 Related endpoints Was this page helpful?

Tell us how we can improve this guide.

Canopy