vault.totp_use_backup

Scope: vault:write

Pop one single-use backup code from a TOTP credential. The popped code is moved from data.backupCodes into data.usedBackupCodes (kept as an audit trail) and returned. Use this when the live TOTP code is unavailable (clock skew, lost device).

Parameters

Name	Type	Required	Description
`name`	`string`	Yes	Credential name with backup codes

Example

Agent: "I can't reach the TOTP device — use a backup code for GitHub"

-> vault.totp_use_backup({ name: "github-2fa" })

Returns

{
  "code": "abcd-1234",
  "remaining": 7
}

Field	Type	Description
`code`	`string`	The consumed backup code. Single-use — never returned again.
`remaining`	`number`	Backup codes still unused after this call.

Notes

The operation is atomic — concurrent calls cannot return the same code.
Used codes remain visible via vault.get under data.usedBackupCodes for audit purposes.
To check backupCodesRemaining without consuming a code, call vault.totp.

REST Equivalent

POST /v0/vault/:name/totp/backup