API Docs
TOTP (2FA)

TOTP API

TOTP (Time-based One-Time Password) endpoints manage two-factor authentication for user accounts. All endpoints require a JWT access token.

Setup TOTP

Generate a new TOTP secret and provisioning URL. The secret is not yet active until confirmed via the Enable endpoint.

POST /auth/totp/setup

Requires: JWT access token with step_up claim.

Response — 200 OK

{
  "secret": "JBSWY3DPEHPK3PXP",
  "otpauthUrl": "otpauth://totp/vaultctl:alice@example.com?secret=JBSWY3DPEHPK3PXP&issuer=vaultctl&algorithm=SHA1&digits=6&period=30"
}
FieldDescription
secretBase32-encoded TOTP secret for manual entry
otpauthUrlURI for QR code scanning by authenticator apps

Example

curl -X POST https://vault.example.com/api/v1/auth/totp/setup \
  -H "Authorization: Bearer <step_up_token>"

Enable TOTP

Confirm and activate TOTP by providing a valid code from the authenticator app. This verifies the user has successfully configured their authenticator.

POST /auth/totp/enable

Request

{
  "code": "123456"
}

Response — 204 No Content

No response body.

Errors

  • 400 INVALID -- Invalid TOTP code

Example

curl -X POST https://vault.example.com/api/v1/auth/totp/enable \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

Verify TOTP

Validate a TOTP code during the two-factor authentication step of login.

POST /auth/totp/verify

Request

{
  "code": "654321"
}

Response — 204 No Content

No response body.

Errors

  • 400 INVALID -- Invalid TOTP code

Example

curl -X POST https://vault.example.com/api/v1/auth/totp/verify \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"code": "654321"}'

Disable TOTP

Deactivate two-factor authentication for the account.

POST /auth/totp/disable

Requires: JWT access token with step_up claim.

Response — 204 No Content

No response body.

Errors

  • 403 STEP_UP_REQUIRED -- Step-up token not provided

Example

curl -X POST https://vault.example.com/api/v1/auth/totp/disable \
  -H "Authorization: Bearer <step_up_token>"

Typical Setup Flow

Obtain a step-up token

Re-verify your master password to get a step-up access token.

curl -X POST https://vault.example.com/api/v1/auth/step-up \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"authHash": "base64-encoded-auth-hash"}'

Generate the TOTP secret

curl -X POST https://vault.example.com/api/v1/auth/totp/setup \
  -H "Authorization: Bearer <step_up_token>"

Scan the QR code

Use the otpauthUrl from the response to generate a QR code or enter the secret manually in your authenticator app.

Confirm with a code

curl -X POST https://vault.example.com/api/v1/auth/totp/enable \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

Replay protection (H6): Each TOTP code can only be used once within its 30-second window. Replaying a recently used code will be rejected, even if it is still technically valid for the current time step.

FoldersUsers