Security | Twentybaan API

Key storage

API keys and OAuth tokens should be treated like passwords. Keep them server-side and never embed them in public frontends.

Store secrets in environment variables or a secret manager, not in your git repo.
Never log raw keys or Authorization headers.
Do not paste keys into support tickets or email. If you need help, share timestamps and endpoint paths instead.
If you run a proxy, make sure it does not expose Authorization headers to downstream logs.

Example

# Keep keys out of your source code. Prefer environment variables.
export TWENTYBAAN_API_KEY="YOUR_API_KEY"

Rotation

Rotate keys regularly and always rotate immediately if you suspect a leak. If a key is revoked, requests will return 401.

Create or revoke keys in Settings → Integrations.
Deploy the new key to your servers before switching production traffic.
Verify with a simple request like GET /v1/me/.

Least privilege

Keep scopes as small as possible. Scopes are enforced for both API keys and OAuth tokens. Missing scopes return 403.

Use only the read scopes your integration needs.
Create separate keys per integration so you can revoke one without breaking others.
Prefer OAuth when you need user-by-user authorization for third-party apps.

Rate limits

We apply rate limits to keep the API stable and reduce abuse. If you exceed limits you will receive 429.

Retry with exponential backoff plus jitter.
Cache responses where it makes sense instead of polling frequently.
Do not brute force API keys. Repeated unauthorized attempts are throttled per IP.

See Errors → Rate limits and abuse for the current defaults.

IP allowlisting (optional)

If your integration runs from stable egress IPs, we can optionally restrict a key to a fixed allowlist. This is not enabled by default because many integrations run from dynamic IPs.

If you want IP allowlisting, email support@twentybaan.com with your account email, the integration name, and the exact public IP addresses to allow.