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

Confirm TOTP

Activates a pending TOTP MFA enrollment by verifying the first valid code from the authenticator app.

On success, the mfa_-prefixed factor record is marked verified and MFA becomes active for the end-user's sign-in flows.

An incorrect code returns an error without consuming the enrollment.

Parameters
projectSlug *path

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

It is unique within the org.

Request body
factorId *string

The factor.id from the enroll response (eumf_...).

code *string

A current code from the authenticator app just set up.

currentCodestring

A current code from an authenticator the end user already has confirmed.

Required when adding a second or later authenticator; without it the request gets 401 K9O_MFA_REQUIRED.

Responses
HTTPK9O CodeDescription
200Success
401K9O_SESSION_EXPIREDYour session has expired or been revoked. Sign in again to continue.
401K9O_INVALID_CREDENTIALSThe TOTP code you entered is incorrect. Check your authenticator app and try again.
401K9O_MFA_REQUIREDAdding a further authenticator needs a current code from one already confirmed (currentCode).
404K9O_END_USER_NOT_FOUNDNo account was found for the provided identity.
429K9O_RATE_LIMITEDToo many wrong codes for this authenticator; try again in 15 minutes.
Response body (200)
data *object

The confirmed authenticator, and new session tokens when the end user's sessions were ended.

factor *object

The authenticator that was confirmed.

id *string

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

verifiedAt *string <date-time>

When the authenticator was confirmed.

It is asked for at every sign-in after this.

sessionobject

Present only when this is the end user's first confirmed authenticator.

Every existing session of the end user, the caller's included, was ended because none was made with a code; use these new tokens instead.

accessToken *string

A signed JWT that authenticates the end user to this project's API.

Send it as Authorization: Bearer <accessToken>.

Its subject (sub) is the end user's id (eu_...), its audience (aud) is the project id (proj_...), and its issuer is the API origin of the region that holds the end user.

It lives for the project's end-user access token lifetime: 30 minutes by default, settable from 5 to 60 minutes. expiresAt is when it expires.

It cannot be revoked early: signing out or revoking sessions stops the next refresh, but a token already issued stays valid until expiresAt.

refreshToken *string

An opaque secret (43 base64url characters) that gets a new access token from POST /@{projectSlug}/gate/refresh.

Store it securely and never send it anywhere else.

It is single use: every refresh returns a new refresh token, and sending the one it replaced a second time ends the whole session.

It stops working when the session ends: on sign-out, a password reset, a revoke-all, or when the project's session limits are reached (by default 30 days without a refresh, or 90 days after sign-in, whichever comes first).

expiresAt *string <date-time>

When accessToken expires.

Refresh before this time to keep the end user signed in.

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.confirm({
  factorId: 'string',
  code: 'string'
})

Showing example in TypeScript

Request example
{
  "factorId": "string",
  "code": "string"
}
Response example (200)
{
  "data": {
    "factor": {
      "id": "string",
      "verifiedAt": "string"
    },
    "session": {
      "accessToken": "string",
      "refreshToken": "string",
      "expiresAt": "string"
    }
  }
}

More in Sign-in & Sessions