# Secrets

## Register a TOTP secret

**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"
        }'
```

#### Response

```json
{
  "status": "OK",
  "totp_secret": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "algorithm": "SHA1",
    "created_at": "2026-04-05T12:00:00Z",
    "digits": 6,
    "issuer": "GitHub",
    "label": "GitHub - agent@example.com",
    "period": 30,
    "secret": "JBSWY3DPEHPK3PXP"
  }
}
```

## List TOTP secrets

**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"
```

#### Response

```json
{
  "status": "OK",
  "totp_secrets": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "algorithm": "SHA1",
      "created_at": "2026-04-05T12:00:00Z",
      "digits": 6,
      "issuer": "GitHub",
      "label": "GitHub - agent@example.com",
      "period": 30,
      "secret": "JBSWY3DPEHPK3PXP"
    }
  ]
}
```

## Delete a TOTP secret

**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"
```

#### Response

```json
{
  "status": "OK"
}
```

## Domain Types

### Secret Create Response

- `SecretCreateResponse object { status, totp_secret }`

  - `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

### Secret List Response

- `SecretListResponse object { status, totp_secrets }`

  - `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

### Secret Delete Response

- `SecretDeleteResponse object { status }`

  - `status: optional string`