Skip to content

Start two-factor setup

POST
/account/security/2fa

Starts setting up two-factor authentication with an authenticator app. The response has a new secret, as base32 text to type into the app and as an otpauth:// link the app can open.

Add the secret to your app, then send a current code to POST /account/security/2fa/confirm to turn two-factor authentication on. Until you confirm, signing in works as before. Calling this again before then replaces the secret, so only the newest one works. Once two-factor authentication is on you get 409; turn it off with DELETE /account/security/2fa first if you want a new secret.

The secret is stored encrypted and only this response shows it. Codes are six digits and change every 30 seconds. Your password isn’t asked for, and an API token works here as well as the session cookie, although only the cookie is listed under Authorizations.

Setup started. Confirm it with a code from your app.

object
secret_base32
required

The secret as base32 text without padding, for typing into an authenticator app by hand.

string
otpauth_url
required

An otpauth://totp/ link with the same secret, labelled artist-alley and your username, or user- and your user ref if you have no username. Open it on a device with an authenticator app, or show it as a QR code to scan; the web app shows the link and the secret, not a QR code.

string

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"
}

Two-factor authentication is already on. Turn it off first to get a new secret.

object
error
required

Human-readable error summary

string
Example
the request could not be completed