> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agent-loadout.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TOTP Codes API — Get Authenticator Codes from the Vault

> Retrieve live 6-digit authenticator codes from the vault using get_totp_code. The raw TOTP secret is never exposed by any endpoint.

If you store a TOTP secret in the vault, the agent can retrieve the current 6-digit authenticator code without ever seeing the raw secret. This lets you automate logins that require two-factor authentication — the vault handles the time-based math and returns only the code that is valid right now.

## Get the current TOTP code

`GET /api/v1/vault/:id/totp` returns the current authenticator code for a credential stored with `kind: totp`. Requires **vault:use**.

The equivalent MCP tool is `get_totp_code`.

```bash title="Get a TOTP code" theme={null}
curl -s https://agent-loadout.com/api/v1/vault/<CREDENTIAL_ID>/totp \
  -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN"
```

### Response fields

<ResponseField name="code" type="string">
  The current 6-digit authenticator code.
</ResponseField>

<ResponseField name="valid_until" type="string">
  ISO 8601 timestamp when this code expires and the next one becomes active.
</ResponseField>

<ResponseField name="period" type="number">
  The TOTP period in seconds (typically 30).
</ResponseField>

<Note>
  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.
</Note>

## Store a TOTP secret

Store a TOTP secret when creating a credential by setting `kind: totp` and providing the base32-encoded secret in the `secret` field. You can also add a TOTP secret to an existing credential with `PATCH /api/v1/vault/:id` (or the `update_credential` MCP tool).

<CodeGroup>
  ```bash title="Create a TOTP credential" theme={null}
  curl -s -X POST https://agent-loadout.com/api/v1/vault \
    -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"name":"Hosting portal","kind":"totp","secret":"JBSWY3DPEHPK3PXP"}'
  ```

  ```bash title="Add TOTP to an existing credential" theme={null}
  curl -s -X PATCH https://agent-loadout.com/api/v1/vault/<CREDENTIAL_ID> \
    -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"secret":"JBSWY3DPEHPK3PXP"}'
  ```
</CodeGroup>

## MCP tool

From a chat client, use the `get_totp_code` tool directly:

| Tool            | Scope required | Description                                         |
| --------------- | -------------- | --------------------------------------------------- |
| `get_totp_code` | vault:use      | Current authenticator code for a stored TOTP secret |

<Tip>
  Use `get_totp_code` to automate portal logins that require 2FA. The agent retrieves the live code at the moment it's needed — no raw secrets stored in code, no secrets visible in the chat transcript.
</Tip>