Skip to main content
POST/gate/mfa/totp/enroll

Enroll TOTP

Initiates TOTP (time-based one-time password) MFA enrollment for the authenticated end-user, returning a provisioning QR code and the raw TOTP secret for scanning with an authenticator app.

Ten single-use recovery codes are generated at this step and must be saved before enrollment is confirmed.

Enrollment is not active until confirmed via the confirm endpoint.

Parameters
projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Request body
labelstring

A name for the authenticator, shown in the methods list.

Default TOTP.

Responses
HTTPK9O CodeDescription
200Success
401K9O_SESSION_EXPIREDYour session has expired or been revoked. Sign in again to continue.
404K9O_END_USER_NOT_FOUNDNo account was found for the provided identity.
Response body (200)
data *object

The authenticator app that was enrolled.

factor *object

The new, unconfirmed authenticator.

Confirm it with a code from the app.

id *string

The authenticator's id (eumf_...).

secret *string

The TOTP seed, base32.

It is shown only in this response and is never readable again: show it (or uri as a QR code) to the end user once and do not store it.

The authenticator is unusable until confirmed.

uri *string

An otpauth://totp/... provisioning URI with the seed, issuer and settings (SHA1, 6 digits, 30-second period).

Render it as a QR code for the authenticator app to scan.

meta *any

Request metadata: cost, timing and the request and trace ids.

TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.gate.mfa.totp.enroll({
  label: 'string'
})

Showing example in TypeScript

Request example
{
  "label": "string"
}
Response example (200)
{
  "data": {
    "factor": {
      "id": "string",
      "secret": "string",
      "uri": "string"
    }
  }
}

More in Sign-in & Sessions