TOTP

Two-factor authentication protects your accounts, but it creates a problem for automation. When your staging environment requires a 6-digit code from an authenticator app to log in, your CI tests can't get past the login screen. The common workarounds are bad: disabling 2FA in staging leaves it untested and less secure, and sharing authenticator app access across a team is fragile and a security risk.

TOTP (Time-based One-Time Password) is the standard behind authenticator apps like Google Authenticator and Authy. The app and the server share a secret key, and the app uses it to generate a new code every 30 seconds. Bounce House lets you register that secret key via API and request the current valid code on demand, so your CI tests and AI agents can complete two-factor challenges the same way a human would, without disabling security or sharing devices.

Register a secret

curl -X POST https://api.bouncehouse.cloud/api/accounts/me/totp \
  -H "Authorization: Bearer bh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"label": "staging-admin", "secret": "<base32-encoded-key>", "issuer": "MyApp", "digits": 6, "period": 30}'

Returns {id, label, issuer, digits, period, created_at}. The secret value is encrypted at rest and never returned in subsequent API calls.

Parameters:

• label — unique identifier (409 if duplicate)
• secret — base32-encoded TOTP shared key
• issuer — optional, the service name
• digits — code length (default 6)
• period — code rotation interval in seconds (default 30)

Generate a code

curl https://api.bouncehouse.cloud/api/accounts/me/totp/{secret_id}/code \
  -H "Authorization: Bearer bh_your_key"

Returns {code, valid_for_seconds}.

List secrets

curl https://api.bouncehouse.cloud/api/accounts/me/totp \
  -H "Authorization: Bearer bh_your_key"

Secret values are never exposed — only {id, label, issuer, digits, period, created_at}.

Delete a secret

curl -X DELETE https://api.bouncehouse.cloud/api/accounts/me/totp/{secret_id} \
  -H "Authorization: Bearer bh_your_key"