Skip to content

Confirm two-factor setup

POST
/account/security/2fa/confirm

Turns on two-factor authentication. Send a current code from the app you added the secret to, and the response gives you ten recovery codes. Save them somewhere safe: this is the only time they’re shown.

From then on, signing in with a password also needs a code from the app or a recovery code. If the server can’t read your two-factor settings at sign-in, it lets the password through on its own and logs a warning.

A code from the previous or next 30 seconds also works. A wrong code, no setup to confirm, or a setup that’s already confirmed gets a 400. Two-factor authentication is switched on before the recovery codes are made: if making them fails you get a 500 and no new codes, but two-factor authentication may already be on. Check with GET /account/security/2fa and make new codes with POST /account/security/2fa/recovery/regenerate. An API token works here as well as the session cookie.

object
code
required

The current six-digit code from your authenticator app.

string

Two-factor authentication is on. The recovery codes are shown this once.

object
recovery_codes
required

Ten recovery codes, each ten letters and digits split by a hyphen, like K7QX2-MZP4A. Use one in place of an app code when you sign in; case and the hyphen don’t matter. The server tries to mark each accepted code as used. If that fails, or two sign-ins use the same code at once, the code can work more than once. Only a hash of each code is stored, so they can’t be shown again.

Array<string>

The code didn’t match, or there’s no unconfirmed setup to confirm.

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}