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 a hash of it. 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/upload-header-imagesend_whatsapp
POST /emailsend_email
POST /broadcasts/validatenone - any valid key

A key without the required scope receives 403 Forbidden - API key does not have <scope> permission.

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. An empty whitelist allows any source address.

Entries are matched by exact string equality against the caller’s resolved IP. CIDR blocks and ranges are not supported - list every egress address individually.

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 was deactivated (not revoked)API key is inactive
401Key has expiredAPI key has expired
403Caller IP not in the API key’s whitelistRequest IP is not in the API key whitelist
403Key lacks the endpoint’s scopeAPI key does not have send_sms permission
403Channel subscription inactiveClient does not have an active SMS channel subscription

Best practices

  • Treat keys as secrets. Store them in a secrets manager. Never commit to source control.
  • Use a separate key per environment and per service, so one can be revoked without taking the others down.
  • 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.

Sessions vs. API keys

The Teekrr dashboard signs you in with a short-lived browser session; that session is for the web UI only and is not a supported way to call the API.

As an external integrator, always authenticate with an API key over the Authorization: Bearer header. It is the only credential type covered by these docs, and the only one with scopes, IP whitelisting, expiry, and revocation.