Settingsbeginner

What are API Keys?

API keys (sa_live_* / sa_test_*) authenticate external systems to Atender's tenant API. Each key has scopes that gate which endpoints it can hit, a rate-limit tier, and an environment (production vs sandbox). Used for integrations, scripts, and the API channel.

4 min read

What are API Keys?

API keys authenticate external systems calling Atender’s tenant API. They’re how a script syncs knowledge-base content, how an integration creates contacts, how a webhook receiver verifies a callback came from your tenant. Each key is a long, hard-to-guess string that starts with sa_live_ (production) or sa_test_ (sandbox).

What a key controls

Every API key carries four properties that decide what it can do:

  • Scopes — Which endpoints the key is allowed to hit. A knowledge:read key can read articles but not write them. See scopes reference
  • Environment — production (sa_live_*) hits real tenant data. sandbox (sa_test_*) hits a separate sandbox tenant for testing
  • Rate limit tier — How many requests per minute / day the key is allowed. See rate limits reference
  • Active state — Disabled keys reject all requests; useful for temporary suspensions without rotation

A request that’s missing scope, exceeding rate limit, or using an inactive key is rejected before it reaches the underlying handler.

What keys are used for

  • Doc-as-code KB sync (the push_kb.py script) — knowledge:read, knowledge:write
  • Creating contacts from your CRM — contacts:write
  • Sending messages from a custom integration — conversations:write
  • Reading conversation analytics for a BI dashboard — analytics:read
  • Webhook delivery from Atender to your system — (not a scope — webhooks are configured separately)
  • The API Channel (programmatic conversation creation) — conversations:write plus channel-specific scopes

Authentication

Send the key as a Bearer token in the Authorization header:

Authorization: Bearer sa_live_<rest-of-key>

Atender’s API responds with a 401 if the key is missing, malformed, or revoked. With a 403 if the key is valid but doesn’t have the required scope for the endpoint. With a 429 if the key is over its rate limit.

Production vs sandbox

Two completely separate environments:

  • Key prefix — sa_live_ — sa_test_
  • Data — Real tenant data — Isolated sandbox tenant
  • Use for — Live integrations, production scripts — Testing, development, integration verification
  • Rate limits — Per the tier — Same tier limits, but typically lower volume in practice

A key from one environment can’t access the other. Tests against sandbox can be aggressive without polluting production data.

Where to start

Tags

Getting StartedConcept
Back to Settings