Contember supports TOTP-based two-factor authentication. Once enabled for a person, every sign-in (signIn and signInPasswordless) requires the current OTP code in addition to the regular credentials.

All three OTP mutations are self-service — they operate on the calling person. An administrator cannot enable or disable 2FA on someone else's behalf; the only admin lever is disablePerson + forceSignOutPerson to lock the account out entirely.

Enabling 2FA

The setup is a two-step exchange:

1. Prepare

mutation {
  prepareOtp(label: "Contember Admin") {
    ok
    result {
      otpUri
      otpSecret
    }
  }
}
  • label is the human-readable name the authenticator app will show. Defaults to "Contember".
  • otpUri is a otpauth:// URI — render it as a QR code for the user.
  • otpSecret is the raw shared secret, for users who prefer to type it manually.

prepareOtp is idempotent — calling it again rotates the secret. If the person already had 2FA enabled, an audit 2fa_disable entry is written before the new pair is issued (because the previous secret is now invalid).

2. Confirm

mutation {
  confirmOtp(otpToken: "123456") {
    ok
    error { code developerMessage }
  }
}

The client asks the user to read the current code from their authenticator app and submits it. The token is validated against the secret created by prepareOtp. On success, 2FA is activated for the person.

Errors:

CodeCause
NOT_PREPAREDprepareOtp was not called for this person.
INVALID_OTP_TOKENThe submitted code does not match.

A successful confirm records 2fa_enable in the audit log; a rejected one records the failure too.

Disabling 2FA

mutation {
  disableOtp {
    ok
    error { code }
  }
}

Errors:

CodeCause
OTP_NOT_ACTIVE2FA is not enabled for this person.

Records 2fa_disable in the audit log.

Re-authentication for MFA changes

Available since 2.2

With login.mfaChangeRequiresReauthentication enabled (it is off by default), a session alone cannot remove or replace a second factor. These mutations then take the current password or a current TOTP code:

mutation {
  disableOtp(currentPassword: "…") {
    ok
    error { code }
  }
}
MutationRequires re-authentication
disableOtp(currentPassword, otpToken)always
disableEmailOtp(currentPassword, otpToken)always
regenerateBackupCodes(currentPassword, otpToken)always
prepareOtp(label, currentPassword, otpToken)only while a TOTP is active (rotation); enrolling the first TOTP does not

Additional error codes, returned in error.code of each mutation:

CodeCause
REAUTHENTICATION_REQUIREDNeither currentPassword nor otpToken was passed.
INVALID_PASSWORDcurrentPassword does not match.
INVALID_OTP_TOKENotpToken is not a current code of the active TOTP.
RATE_LIMIT_EXCEEDEDThe person made more than 5 re-authentication attempts within 15 minutes.

prepareOtp gained an error field for these codes. A person with neither a password nor an active TOTP (for example signed up through an identity provider, using e-mail OTP only) cannot make these changes while the option is on; an administrator can use resetPersonMfa. Failed attempts are recorded in the audit log under the action's type (2fa_disable, 2fa_enable, backup_code_regenerated). Every attempt that passes a credential counts, including successful ones and those for an e-mail change; the limit is fixed and shared by all re-authenticating mutations, so a stolen session cannot guess TOTP codes. With the option off the new arguments are ignored.

Sign-in with 2FA enabled

signIn and signInPasswordless accept an otpToken argument. When 2FA is enabled and the token is missing or wrong:

MutationMissing tokenWrong token
signInOTP_REQUIREDINVALID_OTP_TOKEN
signInPasswordlessOTP_REQUIREDINVALID_OTP_TOKEN

Clients should react to OTP_REQUIRED by prompting for the code and retrying the same mutation with otpToken populated.

Available since 2.2

Each TOTP code is accepted once. After a code is accepted (by a sign-in or any other check of the active TOTP), that code and every code of an earlier time step answer INVALID_OTP_TOKEN; the person waits for the next code (at most 30 seconds). Enabling, re-enrolling, disabling or resetting TOTP starts over.

Reading a person's MFA state

The Person type exposes two independent, read-only MFA flags, so a UI can show each method's status separately:

FieldMethod
otpEnabledTOTP authenticator (the flow documented above).
emailOtpEnabledE-mail one-time-password 2FA — a separate method enabled via initEmailOtp / confirmEmailOtp / disableEmailOtp.
emailOtpEnabled available since 2.2

Both are queryable wherever a Person is reachable — me, personById, the persons listing, and projectBySlug { members { identity { person } } }:

query {
  me {
    person {
      otpEnabled
      emailOtpEnabled
    }
  }
}

The flags are independent: a person may have TOTP on, e-mail OTP on, both, or neither.

Where 2FA does not apply

  • signInIDP — the identity provider is responsible for second-factor enforcement. Contember does not re-check OTP after a successful IDP callback.
  • createSessionToken — admin impersonation bypasses 2FA by design.
  • Permanent API keys — 2FA only protects person logins; permanent keys are credentials in their own right.