Skip to content
Sendblue Docs
Get Started
API Reference
V2
Totp
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 ParametersJSONExpand Collapse
algorithm: optional "SHA1" or "SHA256" or "SHA512"

Hash algorithm

One of the following:
"SHA1"
"SHA256"
"SHA512"
digits: optional 6 or 8

Code length

One of the following:
6
8
issuer: optional string

Service name (e.g. “GitHub”, “Google”)

label: optional string

Human-readable label for this secret (e.g. “GitHub - [email protected]”). 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.

ReturnsExpand Collapse
status: optional string
totp_secret: optional object { id, algorithm, created_at, 5 more }
id: optional string

Unique identifier for this TOTP secret

formatuuid
algorithm: optional "SHA1" or "SHA256" or "SHA512"

Hash algorithm used

One of the following:
"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

Register a TOTP secret

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 - [email protected]",
          "secret": "JBSWY3DPEHPK3PXP",
          "uri": "otpauth://totp/GitHub:agent%40example.com?secret=JBSWY3DPEHPK3PXP&issuer=GitHub"
        }'
{
  "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 - [email protected]",
    "period": 30,
    "secret": "JBSWY3DPEHPK3PXP"
  }
}
Returns Examples
{
  "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 - [email protected]",
    "period": 30,
    "secret": "JBSWY3DPEHPK3PXP"
  }
}