1. Docs
  2. API Reference
  3. Answer the sign-in challenge with an authenticator app code

Answer the sign-in challenge with an authenticator app code

POST/v1/auth/mfa/challenge/totp

Answers the second-factor challenge /v1/auth/login raised, with a 6-digit authenticator-app code against the pending challenge_token. On success the interrupted sign-in resumes with what the challenge proved: the same response and cookies password login gives (a bound session, or the Account picker with a pre-auth cookie), remember deciding whether the refresh cookie persists. remember_device: true also stores a remembered device for the shortest trusted_device_days across the user's Accounts and sets the ca_mfa_trusted_device cookie, and device_remembered says whether it did. Public (the challenge token is the credential); 401 when the token or code is wrong, 403 when the user belongs to no Account. Rate-limited to 10 requests per minute.

Request body

application/json

challenge_tokenstring Required

Challenge token returned by /v1/auth/login when `requires_mfa_challenge` was true.

codestring Required

6-digit code from the authenticator app.

rememberboolean Optional

Keep the session on this device: persist the refresh cookie across browser restarts, as the `remember` flag on `/v1/auth/login` does. Default false.

remember_deviceboolean Optional

When true, remember this device so future password sign-ins from this browser skip the second factor, for as long as the shortest `trusted_device_days` across the user's Accounts allows. The response's `device_remembered` says whether a device was stored. Default false.

Responses

application/json

  • dataLoginResponseDto*

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

LoginResponseDtoView all properties on this resource
Request
curl -X POST "https://auth.canopy-io.com/v1/auth/mfa/challenge/totp" \
  -H "Content-Type: application/json" \
  -d '{
    "challenge_token": "string",
    "code": "123456",
    "remember": false,
    "remember_device": false
  }'
Response
{
  "data": {
    "mfa_enrollment_pending": false,
    "grace_expires_at": "2026-04-20T12:00:00.000Z",
    "requires_mfa_enrollment": false,
    "mfa_enrollment": {
      "enrollment_token": "string",
      "available_factors": [
        "totp"
      ],
      "totp": {
        "otpauth_uri": "string",
        "manual_entry_key": "string"
      }
    },
    "requires_account_selection": false,
    "requires_mfa_challenge": false,
    "mfa_challenge": {
      "challenge_token": "string",
      "available_factors": [
        "totp"
      ],
      "expires_at": "2026-04-20T12:00:00.000Z"
    },
    "device_remembered": false,
    "recovery_codes": [
      "string"
    ],
    "expires_in": 0,
    "user": {
      "id": "string",
      "email": "string",
      "first_name": "string",
      "last_name": "string"
    },
    "access_token": "string",
    "token_type": "string",
    "default_environment_slug": "string",
    "accounts": [
      {
        "account_id": "string",
        "account_name": "string",
        "account_slug": "string",
        "account_role": "string",
        "applications": [
          {
            "id": "string",
            "name": "string",
            "slug": "string"
          }
        ]
      }
    ],
    "pending_account_creation": false
  }
}
 Related endpoints
POSTAnswer the sign-in challenge with a recovery code
POSTGet passkey assertion options for the sign-in challenge
POSTAnswer the sign-in challenge with a passkey
POSTEnroll an authenticator app to complete a sign-in that required one
POSTGet passkey creation options to complete a sign-in that required a factor
POSTEnroll a passkey to complete a sign-in that required a factor
 Was this page helpful?

Tell us how we can improve this guide.

Canopy