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 & MCP. You’ll see a list of existing keys, if any, with names, creation dates, scopes, and expiration details.
2. Click Create Key.
3. In the dialog, fill in:
   Key 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.
   Permissions — check the scopes the key needs. At least one is required; with none ticked, the picker warns “No permissions selected. Pick at least one, or choose Read only to start” and Create key stays disabled.
   Set an end date — optional. Turn this on if the key should stop working automatically on a specific date, then choose the date. The date has to be in the future — the earliest the picker offers is tomorrow.
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_... if you turned on Sandbox/test key in the create pane). If you set an end date, the key list shows when the key stops working.

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 revoke the old one.

If the key has an end date, its row in the key list shows Stops working <date>. On that date, the key stops authenticating. This does not delete or change any Knowledge Base articles, categories, tags, or Agent Stack content created with the key.

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, revoked, or past its end date. A 403 means the key is missing the knowledge:read scope.

Rotating a key

API keys can either run until you revoke them or stop automatically on an optional end date. Use end dates for temporary migrations, short-lived integrations, or keys you want to force-rotate on a schedule.

When a team member with access leaves, you suspect a key has leaked, or a key is nearing its end date:

1. Open Settings → API & MCP.
2. Create a new key with the same scopes and a clear name.
3. Add an end date if you want the new key to stop working automatically, or leave it unset if it should run until revoked.
4. Update your CI / scripts / pipelines to use the new key.
5. Confirm the new key works.
6. Revoke the old key from Settings → API & MCP.

When an end date arrives, the key stops working without affecting the Knowledge Base or Agent Stack content it was used to create or update.

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_* — Sandbox — Created by turning on Sandbox/test key in the create pane, which your workspace needs sandbox mode enabled for. The key carries the scopes you gave it against the same workspace data as a live key.

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

Common gotchas

• The two permissions are labelled “Read knowledge base articles” and “Manage knowledge base articles”, each with its scope identifier — knowledge:read / knowledge:write — printed underneath. Check both for full doc-as-code access.
• At least one permission is required. With none ticked, Create key stays disabled, and a request carrying no scopes is refused with “Choose at least one permission for this key”.
• The key is shown once. If you close the dialog without copying, generate a new key.
• The end date has to be in the future. The earliest date the picker offers is tomorrow.
• An end date only disables the key. It does not delete or change KB articles, categories, tags, or Agent Stack content.
• 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