Skip to content
Sendblue Docs
Get Started
API Reference
V2
Totp
Secrets

Register a TOTP secret

v2.totp.secrets.create(SecretCreateParams**kwargs) -> SecretCreateResponse
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
ParametersExpand Collapse
algorithm: Optional[Literal["SHA1", "SHA256", "SHA512"]]

Hash algorithm

One of the following:
"SHA1"
"SHA256"
"SHA512"
digits: Optional[Literal[6, 8]]

Code length

One of the following:
6
8
issuer: Optional[str]

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

label: Optional[str]

Human-readable label for this secret (e.g. “GitHub - [email protected]”). Required unless uri is provided.

period: Optional[int]

Rotation period in seconds

secret: Optional[str]

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

uri: Optional[str]

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

ReturnsExpand Collapse
class SecretCreateResponse: …
status: Optional[str]
totp_secret: Optional[TotpSecret]
id: Optional[str]

Unique identifier for this TOTP secret

formatuuid
algorithm: Optional[Literal["SHA1", "SHA256", "SHA512"]]

Hash algorithm used

One of the following:
"SHA1"
"SHA256"
"SHA512"
created_at: Optional[datetime]
digits: Optional[int]

Code length (6 or 8)

issuer: Optional[str]

Service name

label: Optional[str]

Human-readable label

period: Optional[int]

Rotation period in seconds

secret: Optional[str]

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

Register a TOTP secret

import os
from sendblue_api import SendblueAPI

client = SendblueAPI(
    api_key=os.environ.get("SENDBLUE_API_API_KEY"),  # This is the default and can be omitted
    api_secret=os.environ.get("SENDBLUE_API_API_SECRET"),  # This is the default and can be omitted
)
secret = client.v2.totp.secrets.create()
print(secret.status)
{
  "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"
  }
}