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

• Generate your first key: Generate an API key
• Pick the right scopes: Scopes reference
• Understand the limits: Rate limits reference
• Watch usage: Monitor API usage
• Rotate compromised keys: Rotate an API key