DocsAPI reference

Verify MFA

Completes a sign-in that stopped at the second factor.

post/api/auth/mfa/verify
Authentication
None
Body
application/json
Version
2026-09-03

Rate limited per account and per address, the same two-sided limit login itself applies and for the same reason: per-address alone lets an attacker work through a list of accounts, per-account alone lets a botnet spread across addresses.

A recovery code is accepted here as well as an authenticator code. The response says which was used, because somebody who has just spent one of ten needs to know now rather than at zero.

Headers#

  • Idempotency-Keystring

    A unique key of your choosing, so this request can be retried safely. The first request with a given key executes; every replay returns that first response unchanged, with Idempotent-Replay: true set.

    Generate one key per action, not per session - reusing a key with a different body is refused with 422 rather than silently replaying the wrong answer. Keys are remembered for 24 hours. A request that failed releases its key, so a retry after fixing the payload runs normally.

    Up to 255 characters

Request body#

application/json · required

MfaVerifyRequest

  • challenge_tokenstringrequired

    8–2048 characters

  • codestringrequired

    4–64 characters

Responses#

  • 200OKapplication/json

    TokenResponse

    • access_tokenstringrequired
    • expires_inintegerrequired
    • organizationOrgReadrequired
      10 fieldsOrgRead
      • idstringrequired
      • namestringrequired
      • plan_tierstringrequired
      • roleOrgRole | stringrequired
      • slugstringrequired
      • accessstring

        One of: member, agency·Default: member

      • is_activeboolean

        Default: true

      • is_currentboolean

        Default: false

      • is_defaultboolean

        Default: false

      • parent_org_idstring | null
    • userUserReadrequired
      9 fieldsUserRead
      • created_atstring (date-time)required
      • emailstringrequired
      • full_namestringrequired
      • idstringrequired
      • is_activebooleanrequired
      • is_verifiedbooleanrequired
      • avatar_urlstring | null
      • is_staffboolean

        Default: false

      • staff_levelstring | null

        One of: view, edit, owner

    • refresh_tokenstring | null
    • supportSupportSessionInfo | null

      Present on a token issued inside a staff support session.

      What the customer surfaces need to draw the banner that says so - whose workspace, whether changes are allowed, and when it ends by itself.

      5 fieldsSupportSessionInfo
      • expires_atstring (date-time)required
      • org_idstringrequired
      • org_namestringrequired
      • session_idstringrequired
      • writebooleanrequired
    • token_typestring

      Default: bearer

    5 response headers
    RateLimit-Limit

    Requests permitted in the current window.

    RateLimit-Remaining

    Requests left in the current window. Back off before it reaches 0.

    RateLimit-Reset

    Seconds until the current window resets.

    X-API-Version

    The dated version of the API contract that served this response, e.g. 2026-09-03. Pin against it; it changes only when a response shape changes incompatibly.

    X-Request-ID

    Quote this in a support request to identify the call.

  • 422Validation error

    The shared error envelope, served as application/problem+json with error.code set to validation_error. Its details name each field that failed and why.

Errors#

Failures use one envelope on every endpoint, described in Retries, versioning and limits. The codes you are most likely to meet here:

  • validation_error · 422 — The payload was well-formed JSON but failed schema validation.
  • idempotency_key_reused · 422 — This `Idempotency-Key` was used before, for a request with a different body.
  • rate_limited · 429 — Too many requests in the current window. The limit is per workspace, and some endpoints add a per-agent limit on top.

More Auth endpoints#

Something unclear or missing? Tell us and we’ll fix it.