Settingsintermediate

API scopes reference

Every scope an API key can be granted, grouped by surface area. Plus the pre-built bundles (basic, integration, full_access) that cover common integration patterns.

5 min read

API scopes reference

Each API key is granted one or more scopes. Each scope gates a related set of endpoints. A key that doesn’t have the required scope for an endpoint gets a 403 response, regardless of who created the key.

Scope structure

Scopes follow a <surface>:<action> pattern:

  • <surface> — the resource area (knowledge, contacts, conversations, etc.)
  • <action> — usually read or write (write implies read)

So knowledge:read lets the key call GET /api/v1/kb/*, while knowledge:write adds POST / PATCH / DELETE on the same surface.

Available scopes

Grouped by surface area. Both :read and :write are available for most resources unless noted.

Knowledge Base

  • knowledge:read — List/get articles, categories, subcategories, tags, search
  • knowledge:write — Create/update/delete articles, categories, subcategories, tags

Used by doc-as-code pipelines and partner systems syncing content.

Conversations

  • conversations:read — List/get conversations, messages, attachments
  • conversations:write — Create conversations, send messages, change status, assign

The most-used scopes for integrations that connect Atender to a custom front-end.

Contacts

  • contacts:read — List/get contacts and their custom field values
  • contacts:write — Create/update/delete contacts; manage custom field values

Used by CRM sync integrations.

Tags

  • tags:read — List tags, see tag tree
  • tags:write — Create/edit/delete tags, assign to conversations

Analytics

  • analytics:read — Pull dashboards, breach rates, conversation volume, agent stats
  • analytics:write — (rare — typically not granted to external integrations)

Used by BI integrations that pull metrics into a data warehouse.

Other surfaces

Scopes also exist for: users, settings, search, bulk (:read / :write), webhooks, channels, automations, agents, snippets, sla, attachments, notifications, teams, csat, status.

The full enum lives in shared/schema/integrations.ts if you need to look up an exact scope name.

Pre-built bundles

For common integration patterns, Atender exposes scope bundles. Pick a bundle instead of selecting individual scopes if your use case fits:

  • basic — contacts:read, conversations:read, tags:read — Read-only integrations, BI dashboards, audit tooling
  • read_all — Every :read scope — Comprehensive monitoring or analytics integrations
  • write_all — Every :write scope — Migration tools, comprehensive sync integrations
  • full_access — Every scope — Power-user integrations, internal tooling
  • analytics_only — analytics:read, conversations:read — Reporting dashboards
  • integration — A balanced set covering most integration needs — Generic third-party integrations (Zapier-style use cases)

Picking minimum scopes

The principle of least privilege applies. Pick the narrowest set of scopes the integration actually needs:

  • Sync KB articles from a markdown vault — knowledge:read, knowledge:write (nothing else)
  • Read-only BI dashboard — analytics:read, conversations:read
  • Customer onboarding tool that creates contacts — contacts:write
  • Internal admin tool that fully manages everything — full_access (only for trusted internal services)

Granting wider scopes than needed increases blast radius if the key is leaked.

Scope hierarchy

:write implies :read for the same surface. A key with knowledge:write can also call GET endpoints under /api/v1/kb/* without needing knowledge:read separately.

This is checked at request time — you don’t need to explicitly add both. Picking :write is sufficient.

See also

Tags

Reference
Back to Settings