1. Docs
  2. API Reference
  3. Begin authenticator app enrollment

Begin authenticator app enrollment

POST/v1/auth/mfa/totp/enroll/start

Begins authenticator-app enrollment for the authenticated administrator by generating a secret and returning the provisioning otpauth:// URI, the manual-entry key, and a sealed five-minute enrollment_token the verify step echoes back. Nothing is stored until a code confirms the secret. Rate-limited to 5 requests per minute.

Authentication

Bearer TokenAuthorization

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

Headers

  • x-mfa-step-up-token

    Required once a factor is already enrolled: a fresh `step_up_token` from `POST /v1/auth/mfa/step-up` or the passkey step-up pair. The first factor needs none.

Responses

application/json

  • dataMfaTotpEnrollStartResponseDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

Rate limit

5 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

MfaTotpEnrollStartResponseDtoView all properties on this resource
Request
curl -X POST "https://auth.canopy-io.com/v1/auth/mfa/totp/enroll/start" \
  -H "x-mfa-step-up-token: value" \
  -H "Authorization: Bearer $CANOPY_TOKEN"
Response
{
  "data": {
    "enrollment_token": "string",
    "otpauth_uri": "otpauth://totp/MFA:alice%40acme.com?secret=JBSWY3DPEHPK3PXP&issuer=MFA",
    "manual_entry_key": "JBSWY3DPEHPK3PXP"
  }
}
 Related endpoints
GETList the caller's enrolled second factors
POSTComplete authenticator app enrollment
POSTBegin passkey enrollment
POSTComplete passkey enrollment
POSTProve a fresh second factor before a sensitive change
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