Get started

Authentication

Bearer API keys, permission scopes, IP whitelisting, and rotation.
View as Markdown

The Teekrr public API uses Bearer API keys. Send your key in the Authorization header on every request:

Authorization: Bearer <your-api-key>

Issuing keys

API keys are issued from the in-app /api-management page (logged-in dashboard). Each key has:

  • A name (your choice)
  • A list of permission scopes (see below)
  • An optional IP whitelist — when non-empty, requests from any other IP are rejected with 403 Forbidden
  • An optional expiry date
  • A revoke action (immediate, no grace period)

The plaintext key value is shown only once at creation. Teekrr stores only the SHA-256 hash. Lost keys cannot be recovered — revoke and reissue.

Permission scopes

Each endpoint requires a specific scope on the calling key:

EndpointRequired scope
POST /smssend_sms
POST /whatsappsend_whatsapp
POST /whatsapp/testsend_whatsapp
POST /whatsapp/upload-header-imagesend_whatsapp
POST /emailsend_email

A key without the required scope receives 403 Forbidden.

IP whitelisting

Set an IP whitelist on a key to lock it down to specific source IPs (e.g. your production servers). When the whitelist is non-empty, requests from any other IP are rejected with 403 Forbidden — Request IP is not in the API key whitelist.

For server-to-server integrations on fixed-IP infrastructure, always set a whitelist.

Auth errors

StatusReasonmessage
401No / malformed Authorization headerMissing or invalid Authorization header
401Bearer token doesn’t match any active keyInvalid API key
401Key was revoked from the dashboardAPI key has been revoked
401Key has expiredAPI key has expired
403Caller IP not in the API key’s whitelistRequest IP is not in the API key whitelist

Best practices

  • Treat keys as secrets. Store in 1Password / AWS Secrets Manager / Vault. Never commit to source control.
  • Use separate keys per environment — staging keys for staging, production keys for production.
  • Use IP whitelisting when keys are deployed on fixed-IP servers.
  • Rotate keys every 90 days. Issue the new key, deploy it, then revoke the old one.
  • Review usage at /api-management → Usage. Every API call is logged with method, path, status, and latency.
  • Use minimal scopes. Don’t issue a send_sms + send_whatsapp + send_email key for a service that only sends SMS.

API key vs. JWT

Teekrr supports two authentication methods on the same endpoints:

  • JWT — used by the in-app web dashboard (cookie-based, short-lived)
  • API key — used by external integrations (Bearer header, long-lived, scoped)

The middleware detects which one you’re using by inspecting the token shape. As an external integrator you should always use API keys — JWT is reserved for the web UI.