Generate a KB API key

To push articles into the Knowledge Base from outside the in-app editor — a doc-as-code pipeline, a migration script, a sync from another system — you need a tenant API key with the right scopes. This walks through generating one.

Before you start

• A user role that can manage API keys (typically admin).
• A clear idea of what you need the key for. Name it accordingly.

Steps

1. Open Settings → API Keys. You’ll see a list of existing keys, if any, with names, creation dates, and scopes.
2. Click Create Key.
3. In the dialog, fill in:
   Name — descriptive. Examples: doc-as-code-pipeline, github-actions-sync, migration-from-zendesk. A future-you needs to know what this key does without opening the script that uses it.
   Scopes — check the scopes the key needs. Leave the section empty if you want the key to inherit all allowed scopes (this is permissive — be explicit unless you have a reason).
4. For Knowledge Base pushes, check both:
   knowledge:read — required for listing existing articles, categories, and tags. The doc-as-code pattern needs this to find existing slugs and decide create vs. update.
   knowledge:write — required to create, update, and delete articles, categories, subcategories, and tags.
5. Click Create Key.

A dialog appears with the new key. It looks like sa_live_abc123def456... (or sa_test_... on dev/staging).

Copy the key — once

A yellow warning sits on the dialog: “Store this key securely. It grants access to your API and cannot be retrieved after closing this dialog.”

This is not a soft warning. Once you close the dialog, the key is hashed in the database and unreadable. If you lose it before saving, you’ll generate a new key and delete the old one.

Save the key to your secret store of choice:

• For local development: a .env file ignored by Git, or a password manager.
• For CI: the repo’s secret store (GitHub Actions secrets, GitLab CI variables, etc.).
• For a team-shared pipeline: 1Password, Vault, or whatever your team uses for shared credentials.

Don’t paste API keys into chat, commit them to a repo, or include them in screenshots.

Verify the key works

A quick curl against the categories endpoint:

export ATENDER_API_KEY="sa_live_..."
curl -s "https://prod.atender.dev/api/v1/kb/categories" \
  -H "Authorization: Bearer $ATENDER_API_KEY" | head -c 500

Use https://staging.atender.dev for staging and https://dev.atender.dev for dev. A 200 response with a list of your tenant’s categories means the key is live. A 401 means the key is wrong or the scope is missing.

Rotating a key

When a team member with access leaves, or you suspect a key has leaked:

1. Open Settings → API Keys.
2. Create a new key with the same scopes and a clear name.
3. Update your CI / scripts / pipelines to use the new key.
4. Confirm the new key works.
5. Delete the old key from Settings → API Keys.

Atender API keys don’t expire on their own — rotate on your own schedule.

Key prefixes — sa_live_ vs sa_test_

• sa_live_* — Production — Real changes to your live KB. Treat with the same care as a production database password.
• sa_test_* — Dev and staging — Sandbox keys. Used during development; a leak here doesn’t expose customer-visible content.

Always use a test key for development work. Promote to a live key only when the pipeline is ready for production.

Common gotchas

• The scope labels in the dialog show as knowledge:read / knowledge:write. These literal strings are the scope identifiers — not a UI bug. Check both for full doc-as-code access.
• An empty Scopes section means “all allowed scopes”. This is permissive; pick explicit scopes unless you really want the key to inherit everything.
• The key is shown once. If you close the dialog without copying, generate a new key.
• Different environments need different keys. A dev key won’t authenticate against production.

See also

• API keys overview
• External KB API
• Doc-as-code with the KB API
• Push articles via API