Multi-factor authentication¶

Multi-factor authentication asks for a second proof of identity after the account password. TEBHOS accepts a TOTP authenticator app and WebAuthn credentials such as passkeys. A one-use backup code works in place of a TOTP code, and sudo mode reuses these factors to protect security-sensitive operations across the API.

All routes on this page are user-only. They require a user session token (Authorization: Bearer <token>). A valid Bot <token> credential is refused with 403 ACCESS_DENIED.

Completing a login with a second factor is described on HTTP authentication. SMS codes are covered on Phone verification and are not usable on TEBHOS.

Authenticator types¶

The user object reports the account's second factors in authenticator_types (see authenticator types) and sets mfa_enabled when the list is not empty.

Password login asks for a second factor whenever the account has TOTP enabled or at least one registered WebAuthn credential. A registered passkey is therefore always a second factor. There is no separate switch.

TOTP parameters¶

TEBHOS validates a TOTP code as a six-digit HMAC-SHA-1 one-time password over a 30-second time step, and accepts one time step of clock skew on either side.

TEBHOS generates the secret. Set up TOTP returns a fresh 160-bit Base32 secret and an otpauth:// URL for a QR code, and stores the secret encrypted until Enable TOTP confirms it with a code. Any secret the client sends is ignored.

Backup code contract¶

An account holds at most one set of 10 backup codes. Each code is two groups of four characters from the lowercase Latin alphabet and the decimal digits, separated by a hyphen, for example a3f2-9kd7. TEBHOS stores the codes so that the set can be shown again later together with which codes are already used.

• Enabling TOTP generates a new set and returns it. Any previous set is replaced.
• Regenerating replaces the whole set with 10 new codes, so every saved code stops working.
• Disabling TOTP deletes every backup code, even when the account keeps passkeys.
• Consuming a code is irreversible.

A backup code is accepted in the mfa_code field of the sudo verification object, in the code field of Disable TOTP, and on the backup code login route described on HTTP authentication.

Sudo mode¶

Sudo mode is a short proof that the person in front of the session is still the account holder. TEBHOS has two independent ways to provide it, and each sudo-protected route accepts exactly one of them.

A grant does not satisfy an inline route, and inline fields do not satisfy a grant route.

A request that presents no acceptable proof fails with 403 SUDO_MODE_REQUIRED:

{
  "error": "SUDO_REQUIRED",
  "code": "SUDO_MODE_REQUIRED",
  "message": "Bu işlem güvenlik onayı gerektirir."
}

The body does not list the available methods. Call Get sudo MFA methods to decide which proof to ask the user for.

A proof that is present but wrong fails with 401 UNAUTHORIZED. This 401 does not mean the session is invalid, so a client must not sign the user out on it.

Accepted proof¶

TEBHOS reads the first field that is present, in this order: sudo_proof, then a non-empty mfa_code, then a non-empty password.

mfa_code is checked as a TOTP code first and then as a backup code, and a matching backup code is consumed. sudo_proof must come from Verify passkey assertion.

The mfa_code path draws on a per-account allowance of 10 attempts per 15 minutes (auth:sudo_mfa), charged before the code is checked. The password path draws on 10 attempts per 5 minutes (auth:sudo_pwd). Both are shared by every sudo-protected route.

Sudo verification object¶

Inline sudo routes merge these fields into their own JSON body.

Structure¶

Sudo grant object¶

Structure¶

Sudo MFA methods object¶

Structure¶

MFA backup codes object¶

Structure¶

Example¶

{
  "backup_codes": [
    {"code": "a3f2-9kd7", "consumed": false},
    {"code": "b81c-4nq0", "consumed": true}
  ]
}

MFA backup code object¶

Structure¶

TOTP setup object¶

Structure¶

WebAuthn credential object¶

An account holds at most 10 WebAuthn credentials.

Structure¶

TEBHOS never returns the credential's public key or signature counter.

WebAuthn registration options object¶

TEBHOS returns the values a client needs to build PublicKeyCredentialCreationOptions itself. The TEBHOS web client requests the ES256 (-7) and RS256 (-257) algorithms, which are the only key types TEBHOS can verify.

Structure¶

WebAuthn assertion options object¶

Structure¶

Passkey sudo proof object¶

Structure¶

Get sudo MFA methods¶

GET /auth/sudo/mfa-methods

Returns a sudo MFA methods object describing which proofs the account can present. Sudo mode is not required.

Response¶

Rate limit¶

20 requests per minute for each authenticated user on the sudo:mfa:methods bucket.

Create sudo grant¶

POST /auth/sudo

Proves sudo mode and grants it to the calling session for 5 minutes. Returns a sudo grant object on success.

The grant belongs to the session token that made the request. It does not elevate the same account's other sessions. Calling again from the same session writes a fresh 5-minute grant.

JSON body¶

A sudo verification object. The accepted proof rules apply.

Response¶

Rate limit¶

5 requests per 10 seconds for each client IP on the auth:sudo bucket, plus the per-account allowances described under sudo mode.

Revoke sudo grant¶

DELETE /auth/sudo

Removes the calling session's sudo grant, if any. Returns 204 with an empty body.

Set up TOTP¶

POST /auth/2fa/totp/setup

Generates a new TOTP secret and stores it as pending. Returns a TOTP setup object. Nothing changes on the account until Enable TOTP confirms the secret.

Calling this operation again replaces the pending secret. Sudo mode is not required, because the secret has no effect until it is enabled.

Response¶

Enable TOTP¶

POST /auth/2fa/totp/verify

Confirms the pending secret from Set up TOTP with a current code and enables TOTP. Requires inline sudo mode. Emits a User Update Gateway event.

The response also carries the first set of 10 backup codes. Any previous set is replaced.

JSON body¶

The body extends the sudo verification object with:

Response¶

Errors from the TOTP step use the body {"error": "<CODE>", "message": "..."} with no code member.

Rate limit¶

10 requests per minute for each authenticated user on the user:mfa:totp:enable bucket.

Example¶

curl -X POST https://tebhos.com/api/v1/auth/2fa/totp/verify \
  -H "Authorization: Bearer $TEBHOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "492039", "password": "correct horse battery staple"}'

Enable TOTP (alternate route)¶

POST /users/@me/mfa/totp/enable

Does the same as Enable TOTP but proves sudo mode with a sudo grant instead of inline fields, and returns only the MFA backup codes object.

JSON body¶

Response¶

The other failures match Enable TOTP.

Rate limit¶

10 requests per minute for each authenticated user on the user:mfa:totp:enable bucket.

Disable TOTP¶

POST /users/@me/mfa/totp/disable

Disables TOTP and deletes every backup code. Returns 204 with an empty body. Emits a User Update Gateway event.

The code field is the identity proof: a current TOTP code or an unconsumed backup code. No other sudo field is read.

JSON body¶

Response¶

Rate limit¶

10 requests per minute for each authenticated user on the user:mfa:totp:disable bucket.

List MFA backup codes¶

POST /users/@me/mfa/backup-codes

Returns an MFA backup codes object, replacing the set first when regenerate is true. Requires inline sudo mode.

Neither TOTP nor a verified email is required, so an account with no second factor can prove sudo mode with its password and create a set.

A backup code sent as mfa_code to prove sudo mode is consumed. With regenerate set to false it comes back with consumed set to true.

JSON body¶

The body extends the sudo verification object with:

Response¶

Rate limit¶

6 requests per minute for each authenticated user on the user:mfa:backup_codes bucket, shared with Regenerate MFA backup codes and Count MFA backup codes.

Regenerate MFA backup codes¶

POST /auth/2fa/backup-codes/regenerate

Replaces the backup code set with 10 new codes and returns them as plain strings. Requires inline sudo mode. A request without a body is treated as presenting no proof.

JSON body¶

A sudo verification object.

Response¶

Rate limit¶

6 requests per minute for each authenticated user on the user:mfa:backup_codes bucket.

Count MFA backup codes¶

GET /auth/2fa/backup-codes/list

Returns how many backup codes are still unused, without revealing them. Sudo mode is not required.

Response¶

Rate limit¶

6 requests per minute for each authenticated user on the user:mfa:backup_codes bucket.

List WebAuthn credentials¶

GET /auth/passkeys

Returns the account's credentials, oldest first, as {"passkeys": [...]} with WebAuthn credential objects. Sudo mode is not required.

GET /users/@me/mfa/webauthn/credentials returns the same credentials as a bare array.

Response¶

Rate limit¶

40 requests per 10 seconds for each authenticated user on the mfa:webauthn:list bucket. Both routes share it.

Create WebAuthn registration options¶

POST /auth/passkeys/register-options

Creates a one-use registration challenge and returns a WebAuthn registration options object. Requires inline sudo mode. A request without a body is treated as presenting no proof.

A new challenge replaces any earlier registration challenge for the account.

JSON body¶

A sudo verification object.

Response¶

Rate limit¶

20 requests per 10 seconds for each authenticated user on the mfa:webauthn:registration_options bucket.

Register WebAuthn credential¶

POST /auth/passkeys/register

Stores the credential the browser created for the registration challenge. Returns the new WebAuthn credential object without last_used_at. Emits a WebAuthn Credentials Update Gateway event with the full credential list, and a User Update event.

This route reads no sudo field. The challenge can only come from Create WebAuthn registration options, which required sudo mode.

TEBHOS checks that the client data type is webauthn.create, that its challenge is the account's current registration challenge, and that its origin is the TEBHOS web app (https://tebhos.com). The attestation statement is not verified. The first credential adds the WebAuthn authenticator type.

JSON body¶

Response¶

A failed registration leaves the challenge in place until it expires. A credential ID that is already registered to any account is not stored again, and the request still returns 200.

Rate limit¶

10 requests per minute for each authenticated user on the mfa:webauthn:register bucket.

Rename WebAuthn credential¶

PATCH /auth/passkeys/{credential_id}

Changes a credential's name. Requires inline sudo mode. Emits a WebAuthn Credentials Update Gateway event.

Path parameters¶

JSON body¶

The body extends the sudo verification object with:

Response¶

Rate limit¶

20 requests per 10 seconds for each authenticated user on the mfa:webauthn:update bucket.

Delete WebAuthn credential¶

DELETE /auth/passkeys/{credential_id}

Deletes a credential. Requires inline sudo mode, sent as the JSON body of the DELETE request. Emits a WebAuthn Credentials Update Gateway event and a User Update event.

Sudo mode is checked before TEBHOS looks the credential up, so a request without a proof learns nothing about the credential.

Path parameters¶

JSON body¶

A sudo verification object.

Response¶

Rate limit¶

10 requests per minute for each authenticated user on the mfa:webauthn:delete bucket.

Create passkey assertion options¶

POST /auth/passkeys/assert-options

Creates a one-use assertion challenge for a signed-in account and returns a WebAuthn assertion options object. Use it to turn a passkey into a sudo proof with Verify passkey assertion. Send an empty body.

Response¶

Verify passkey assertion¶

POST /auth/passkeys/assert

Verifies a WebAuthn assertion for the challenge from Create passkey assertion options and returns a passkey sudo proof object.

TEBHOS checks that the client data type is webauthn.get, that the challenge and the origin match, that the credential belongs to the account, and the signature. Supported keys are ES256 and RS256. The signature counter must be greater than the stored counter, except when both are zero, which is how an authenticator without a counter reports. On success the counter and last_used_at are updated and the challenge is consumed.

JSON body¶

Response¶

Rate limit¶

10 requests per 5 minutes for each authenticated user on the auth:pk_assert bucket.

Example¶

const base = "https://tebhos.com/api/v1";
const headers = { Authorization: `Bearer ${token}`, "Content-Type": "application/json" };
const b64u = (buf) => btoa(String.fromCharCode(...new Uint8Array(buf)))
  .replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
const fromB64u = (s) => Uint8Array.from(atob(s.replace(/-/g, "+").replace(/_/g, "/")), (c) => c.charCodeAt(0));

const opts = await fetch(`${base}/auth/passkeys/assert-options`, { method: "POST", headers })
  .then((r) => r.json());

const cred = await navigator.credentials.get({
  publicKey: {
    challenge: fromB64u(opts.challenge),
    rpId: opts.rp_id,
    allowCredentials: opts.allow_credential_ids.map((id) => ({ type: "public-key", id: fromB64u(id) })),
    userVerification: "preferred",
  },
});

const { sudo_proof } = await fetch(`${base}/auth/passkeys/assert`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    credential_id: cred.id,
    client_data_json: b64u(cred.response.clientDataJSON),
    authenticator_data: b64u(cred.response.authenticatorData),
    signature: b64u(cred.response.signature),
  }),
}).then((r) => r.json());

// Use it once, within 5 minutes, on an inline sudo route.
await fetch(`${base}/users/@me/mfa/backup-codes`, {
  method: "POST",
  headers,
  body: JSON.stringify({ regenerate: false, sudo_proof }),
});