Use Backup Code

Scope: vault:write

Pop one single-use backup code from a TOTP credential. The popped code is moved from data.backupCodes to data.usedBackupCodes (kept as an audit trail) so it can never be returned again.

Use this when the live TOTP code is unavailable (clock skew, lost device).

Request

import { Loomal } from "@loomal/sdk";

const loomal = new Loomal({ apiKey: process.env.LOOMAL_API_KEY! });
const { code, remaining } = await loomal.vault.totpUseBackup("github-2fa");

import os
from loomal import Loomal

loomal = Loomal(api_key=os.environ["LOOMAL_API_KEY"])
result = loomal.vault.totp_use_backup("github-2fa")

loomal vault totp-use-backup github-2fa

vault.totp_use_backup(name="github-2fa")

curl -X POST https://api.loomal.ai/v0/vault/github-2fa/totp/backup \
  -H "Authorization: Bearer loid-your-api-key"

Response

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

Errors

Notes

• The operation is atomic — concurrent calls cannot return the same code twice.
• Used codes are preserved under data.usedBackupCodes and visible via GET /v0/vault/:name. They are never returned by vault.totp or this endpoint.
• To inspect remaining backup-code count without consuming one, call GET /v0/vault/:name/totp (returns backupCodesRemaining) or GET /v0/vault/:name (returns the full data.backupCodes array).