Skip to main content

​
Account 2FA

These endpoints manage 2FA on the user’s PassAgent account.

​
Enroll

Begin TOTP 2FA enrollment. Returns a QR code URI and recovery codes. 
POST /api/2fa/enroll
Authentication: Required CSRF: Required Rate limit: 5 requests per 15 minutes Response 200 OK: 
{
  "qrCodeUri": "otpauth://totp/PassAgent:user@example.com?secret=BASE32SECRET&issuer=PassAgent",
  "secret": "BASE32SECRET",
  "recoveryCodes": [
    "a1b2c3d4",
    "e5f6g7h8",
    "i9j0k1l2"
  ]
}
Recovery codes are shown only once during enrollment. Store them in a safe location outside your PassAgent vault.

​
Verify

Verify a TOTP code during enrollment confirmation or login. 
POST /api/2fa/verify
Authentication: Required CSRF: Required Request body: 
{
  "code": "123456"
}
Response 200 OK: 
{
  "verified": true
}
Response 401 Unauthorized: 
{
  "error": "Invalid verification code",
  "verified": false
}

​
Check status

Check the current 2FA enrollment status. 
GET /api/2fa/status
Authentication: Required Response 200 OK: 
{
  "enrolled": true,
  "method": "totp",
  "enrolledAt": "2026-01-15T10:00:00Z"
}

​
Disable

Disable 2FA for the authenticated user. 
POST /api/2fa/disable
Authentication: Required CSRF: Required Request body: 
{
  "code": "123456"
}
A valid TOTP code is required to disable 2FA. Response 200 OK: 
{
  "success": true
}

​
Vault entry TOTP

These endpoints manage TOTP secrets stored alongside password entries in the vault.

​
Get TOTP config

Retrieve TOTP configuration for a vault entry. 
GET /api/passwords/{id}/totp
Authentication: Required Response 200 OK (zero-trust): 
{
  "hasTotp": true,
  "zeroTrust": true,
  "secretEncrypted": {
    "iv": "base64-iv",
    "ciphertext": "base64-ciphertext"
  },
  "algorithm": "SHA-1",
  "digits": 6,
  "period": 30
}
Response 200 OK (legacy Evervault): 
{
  "hasTotp": true,
  "zeroTrust": false,
  "algorithm": "SHA-1",
  "digits": 6,
  "period": 30
}

​
Set TOTP

Store a TOTP secret for a vault entry. The secret must be encrypted client-side before sending. 
POST /api/passwords/{id}/totp
Authentication: Required CSRF: Required Request body: 
{
  "secretEncrypted": {
    "iv": "base64-iv",
    "ciphertext": "base64-ciphertext"
  },
  "algorithm": "SHA-1",
  "digits": 6,
  "period": 30
}
Response 201 Created: 
{
  "success": true
}

​
Delete TOTP

Remove TOTP configuration from a vault entry. 
DELETE /api/passwords/{id}/totp
Authentication: Required CSRF: Required Response 200 OK: 
{
  "success": true
}

​
Get TOTP code (legacy)

Generate a current TOTP code. Only available for legacy Evervault-encrypted secrets. 
GET /api/passwords/{id}/totp/code
Authentication: Required Response 200 OK (legacy): 
{
  "code": "123456",
  "remaining": 18
}
Response 410 Gone (zero-trust): 
{
  "error": "Zero-trust TOTP codes must be generated client-side",
  "code": "GONE"
}
For zero-trust entries, decrypt the secretEncrypted field client-side with your vault key, then generate the TOTP code locally using the HMAC-based algorithm specified in RFC 6238.