Skip to main content
If you store a TOTP secret in the vault, the agent can retrieve its current authenticator code without retrieving the seed. This lets you automate logins that require two-factor authentication. The vault calculates the code and reports how long it remains valid.

Get the current TOTP code

POST /api/v1/vault/:id/totp returns the current authenticator code for a credential with TOTP configured. Requires vault:use, and the credential must be marked agent-readable. The equivalent MCP tool is get_totp_code.
Get a TOTP code

Response fields

string
The current authenticator code. Keep it as a string to preserve leading zeroes.
string
The credential used to generate the code.
number
Seconds until the current code expires.
number
Number of digits in the code, as configured by the authenticator seed or URI.
The raw TOTP secret is never returned by any endpoint after it is stored. Only the current code is accessible, and every call is recorded in the org’s audit history.

Store a TOTP secret

TOTP is an optional field on a login or api_key credential. Pass the base32 seed or otpauth://totp/... URI as totp when creating or updating it. Creating and updating require vault:write. To add TOTP to an existing credential, send only totp in PATCH /api/v1/vault/:id, or use update_credential with credential_id and totp. The secret field changes the password or API key and must not be used for an authenticator seed. The examples below use a sample seed; replace it with the one issued for your account.

MCP tool

From a chat client, use the get_totp_code tool directly:
Retrieve a code just before using it. Keep authenticator codes and credential values out of logs and chat transcripts.