Begin enrolling a time-based one-time password factor
Begin enrolling a time-based one-time password factor
POST/api/v1/auth/mfa/totp/setup
Generates a shared secret and returns it once, with the otpauth://
URI a QR code encodes. The secret is never readable again; a client
that loses it must start enrolment over.
Setup alone does not enable the factor — sign-in keeps working
unchanged until confirmTOTP succeeds, so an abandoned enrolment
cannot lock anyone out. Restarting setup replaces any unconfirmed
secret, which stops a previously displayed QR code from working.
An account that already has a confirmed factor receives 409: allowing
a replacement would let whoever holds a live session swap the second
factor out silently.
Header Parameters
X-CSRF-TokenRequired
string·min 43·max 43
Session-bound CSRF token. It must exactly match the
__Host-assign_csrf cookie sent with the request.
Responses
Cache-Control
string·const no-store
Prevents storage of error responses by clients and intermediaries.
X-Request-ID
string·min 1·max 200
Correlation identifier for the request.
X-Content-Type-Options
string·const nosniff
Prevents user agents from MIME-sniffing the response.
secretRequired
string <password>
The shared secret in unpadded base32, the form authenticator apps
accept when it is typed in by hand.
provisioning_uriRequired
string <uri>
An otpauth://totp/ URI carrying the secret, issuer, algorithm,
digit count, and period.
Cache-Control
string·const no-store
Prevents storage of error responses by clients and intermediaries.
X-Request-ID
string·min 1·max 200
Correlation identifier for the request.
X-Content-Type-Options
string·const nosniff
Prevents user agents from MIME-sniffing the response.
errorRequired
object
Cache-Control
string·const no-store
Prevents storage of error responses by clients and intermediaries.
X-Request-ID
string·min 1·max 200
Correlation identifier for the request.
X-Content-Type-Options
string·const nosniff
Prevents user agents from MIME-sniffing the response.
errorRequired
object
Cache-Control
string·const no-store
Prevents storage of error responses by clients and intermediaries.
X-Request-ID
string·min 1·max 200
Correlation identifier for the request.
X-Content-Type-Options
string·const nosniff
Prevents user agents from MIME-sniffing the response.
errorRequired
object
Cache-Control
string·const no-store
Prevents storage of error responses by clients and intermediaries.
X-Request-ID
string·min 1·max 200
Correlation identifier for the request.
X-Content-Type-Options
string·const nosniff
Prevents user agents from MIME-sniffing the response.
Retry-After
integer·min 1
Seconds until the client may retry.
errorRequired
object
Cache-Control
string·const no-store
Prevents storage of error responses by clients and intermediaries.
X-Request-ID
string·min 1·max 200
Correlation identifier for the request.
X-Content-Type-Options
string·const nosniff
Prevents user agents from MIME-sniffing the response.
errorRequired
object
Retry-After
integer·min 0
Delay in seconds before retrying, when an expected maintenance end is known.
Cache-Control
string·const no-store
Prevents storage of error responses by clients and intermediaries.
X-Request-ID
string·min 1·max 200
Correlation identifier for the request.
X-Content-Type-Options
string·const nosniff
Prevents user agents from MIME-sniffing the response.
