# Totp

## Get Code

**get** `/api/v2/totp/code/{secret_id}`

Generate the current 6- or 8-digit TOTP code for a stored secret, along with how many seconds remain until it rotates.

### Path Parameters

- `secret_id: string`

### Returns

- `code: optional string`

  The current TOTP code

- `expires_in: optional number`

  Seconds until this code rotates

- `status: optional string`

### Example

```http
curl https://api.sendblue.co/api/v2/totp/code/$SECRET_ID \
    -H "sb-api-key-id: $SENDBLUE_API_API_KEY" \
    -H "sb-api-secret-key: $SENDBLUE_API_API_SECRET"
```

# Secrets

## Create

**post** `/api/v2/totp/secrets`

Store an encrypted TOTP secret for your account. Agents can use this instead of a phone-based authenticator app.

Provide either:

- A `uri` (the `otpauth://` URI from a QR code scan), which auto-populates all fields
- A base32 `secret` with optional `label`, `issuer`, `algorithm`, `digits`, and `period`

### Body Parameters

- `algorithm: optional "SHA1" or "SHA256" or "SHA512"`

  Hash algorithm

  - `"SHA1"`

  - `"SHA256"`

  - `"SHA512"`

- `digits: optional 6 or 8`

  Code length

  - `6`

  - `8`

- `issuer: optional string`

  Service name (e.g. "GitHub", "Google")

- `label: optional string`

  Human-readable label for this secret (e.g. "GitHub - agent@example.com"). Required unless `uri` is provided.

- `period: optional number`

  Rotation period in seconds

- `secret: optional string`

  Base32-encoded TOTP secret. Omit to auto-generate one.

- `uri: optional string`

  Full `otpauth://totp/...` URI from a QR code. Overrides all other fields if provided.

### Returns

- `status: optional string`

- `totp_secret: optional object { id, algorithm, created_at, 5 more }`

  - `id: optional string`

    Unique identifier for this TOTP secret

  - `algorithm: optional "SHA1" or "SHA256" or "SHA512"`

    Hash algorithm used

    - `"SHA1"`

    - `"SHA256"`

    - `"SHA512"`

  - `created_at: optional string`

  - `digits: optional number`

    Code length (6 or 8)

  - `issuer: optional string`

    Service name

  - `label: optional string`

    Human-readable label

  - `period: optional number`

    Rotation period in seconds

  - `secret: optional string`

    Base32 secret — only returned on creation, never on list/get

### Example

```http
curl https://api.sendblue.co/api/v2/totp/secrets \
    -H 'Content-Type: application/json' \
    -H "sb-api-key-id: $SENDBLUE_API_API_KEY" \
    -H "sb-api-secret-key: $SENDBLUE_API_API_SECRET" \
    -d '{
          "issuer": "GitHub",
          "label": "GitHub - agent@example.com",
          "secret": "JBSWY3DPEHPK3PXP",
          "uri": "otpauth://totp/GitHub:agent%40example.com?secret=JBSWY3DPEHPK3PXP&issuer=GitHub"
        }'
```

## List

**get** `/api/v2/totp/secrets`

List all stored TOTP secrets for the account. The encrypted secret values are never returned.

### Returns

- `status: optional string`

- `totp_secrets: optional array of object { id, algorithm, created_at, 5 more }`

  - `id: optional string`

    Unique identifier for this TOTP secret

  - `algorithm: optional "SHA1" or "SHA256" or "SHA512"`

    Hash algorithm used

    - `"SHA1"`

    - `"SHA256"`

    - `"SHA512"`

  - `created_at: optional string`

  - `digits: optional number`

    Code length (6 or 8)

  - `issuer: optional string`

    Service name

  - `label: optional string`

    Human-readable label

  - `period: optional number`

    Rotation period in seconds

  - `secret: optional string`

    Base32 secret — only returned on creation, never on list/get

### Example

```http
curl https://api.sendblue.co/api/v2/totp/secrets \
    -H "sb-api-key-id: $SENDBLUE_API_API_KEY" \
    -H "sb-api-secret-key: $SENDBLUE_API_API_SECRET"
```

## Delete

**delete** `/api/v2/totp/secrets/{secret_id}`

Permanently delete a stored TOTP secret.

### Path Parameters

- `secret_id: string`

### Returns

- `status: optional string`

### Example

```http
curl https://api.sendblue.co/api/v2/totp/secrets/$SECRET_ID \
    -X DELETE \
    -H "sb-api-key-id: $SENDBLUE_API_API_KEY" \
    -H "sb-api-secret-key: $SENDBLUE_API_API_SECRET"
```