API Tokens
- What public API tokens are and when you need them
- How to create, view, and manage tokens
- Security best practices for handling tokens
Public API Tokens allow external applications, scripts, and services to authenticate with AutoTalk's API. You manage tokens from the API Tokens page under Integrations in the sidebar.
When you need API tokens
You need an API token whenever an external system needs to communicate with AutoTalk programmatically. Common scenarios include:
- Connecting a CRM or helpdesk system that pushes or pulls data from AutoTalk
- Building a custom integration that sends messages or reads conversations through the API
- Setting up automation scripts that create contacts, update records, or trigger workflows
- Integrating unsupported platforms or internal systems through a custom bridge, such as a Discord notification pipeline
Managing tokens
Viewing existing tokens
Navigate to Integrations > API Tokens. The page lists all of your existing tokens. You can filter the list, open a token to view its details, and delete tokens; tokens can't be edited after creation.
Creating a new token
- On the API Tokens page, click the + button (its tooltip reads "Add new public_api_tokens").
- Review the generated alias or replace it with your own label.
- Choose permissions. Under Permissions, tick what the integration needs in the permissions grid, or start from a preset (Read-only, Operator, Full access) and adjust. At least one is required — a token that grants nothing cannot be saved. Permissions you did not tick may appear ticked and locked: a stronger one you did tick carries them. See Permissions below. Permissions can't be changed afterwards — a token that needs a different set has to be replaced.
- Choose a lifetime. New tokens default to 90 days, with options for 7, 30, 90, 365 days, or never expiring.
- Save the token.
- Copy the generated token or the Codex / Claude Code MCP command immediately. The full token is displayed only once.
Viewing or deleting a token
- Click on any token in the list to view its details, expiration, and usage stats.
- To revoke a token, delete it from the list. Any external system using that token will immediately lose access.
Using tokens in API requests
Pass the token in the x-api-key header of every request to the AutoTalk public API. Keys always start with sk-:
x-api-key: sk-YOUR_API_KEY
A minimal curl example:
curl -H "x-api-key: sk-YOUR_API_KEY" https://api.autotalk.io/v1/self
See the API Reference for the full endpoint catalog.
Alternative: x-jwt-token
The same API also accepts short-lived JWTs via the x-jwt-token header (or the unified x-auth-token header that sniffs the sk- prefix to route automatically). JWTs are issued internally by the actions/security/auth/jwt/generate agent workflow action — they are meant for agents calling the public API on their own company's behalf. External integrations should stick with x-api-key. See Authentication for the full spec.
Security best practices
- Treat tokens like passwords. Never share them in public code repositories, chat messages, or emails.
- Use descriptive names. Label each token with the integration or system it belongs to, so you can identify it later.
- Revoke unused tokens. If an integration is retired or a token is no longer needed, delete it immediately.
- Rotate tokens periodically. Replace tokens on a regular schedule to reduce the risk if one is accidentally exposed.
- Grant the narrowest set that works. At least one permission is required, and a token grants everything its permissions imply — "Run saved workflows", for example, carries whatever the workflow's steps do. Use a separate token per integration so revocation is targeted, and treat a leaked token as a compromise of everything its permissions cover.
Permissions
Permissions are arranged as a small tree: picking a stronger one automatically carries the weaker ones under it, and the picker shows those as already-ticked. Grant the narrowest set the integration actually needs.
| Permission | Name in the API | What it grants |
|---|---|---|
| Read records | data:read | Read-only access to your data and its schemas |
| Create, update and delete records | data:write | Writes to your data, including document functions. Carries data:read |
| Bulk and cascading deletes | data:admin | Destructive, unbounded-fanout deletes. Carries data:write |
| Send messages | messaging:send | Messaging on your channels, and deleting chats and messages |
| Read files | storage:read | Reading and listing stored files |
| Upload files | storage:write | Writing to storage. Carries storage:read |
| Delete files | storage:admin | Deleting files. Carries storage:write and storage:share |
| Share links | storage:share | Creating download URLs usable outside AutoTalk. Carried only by storage:admin — never by read or write |
| Run billed AI | ai:run | LLM generation and transcription that costs money |
| Run saved workflows | workflows:run | Runs a workflow this account already wrote — including the records, messages, files and AI its steps touch. It cannot create, edit or arm one |
| Automation and code | automation:admin | Arbitrary code execution. Also authoring and arming workflows, outbound HTTP, minting tokens, and reading stored secrets |
| Account administration | org:admin | Everything in the ten areas below at once |
| Team | org.team:admin | Invite links and employees |
| Billing | org.billing:admin | Budget, credits and subscriptions |
| Channels | org.channels:admin | Channels and integrations, including moderation actions on the connected platform |
| Custom types | org.types:admin | Creating and changing custom types |
| Webhooks | org.webhooks:admin | Webhook configuration — and therefore configured outbound egress |
| Agents and profiles | org.agents:admin | Agents, transcription profiles and voice profiles |
| API keys | org.keys:admin | Re-issuing an API key's secret |
| Data export | org.export:admin | Data transfer and export |
| Onboarding | org.onboarding:admin | Onboarding flows |
| Agent debug | org.debug:admin | AI agent debug tools |
| Full access | account:admin | Every permission above |
Two things follow from the tree and are worth stating outright:
- "Run saved workflows" carries real authority. A workflow run exercises
whatever its steps do, so this permission carries data, messaging, file and AI
access with it. What it does not carry is authoring: creating, editing or
arming a workflow is
automation:admin. automation:adminis fenced. Nothing implies it except full access. A workflow whose steps run code, call an external URL or mint a token is refused in full unless the key holds it.
A call the token's permissions do not cover is refused with HTTP 403 and the
error code scope_denied. The response names the permission that was missing.
If you suspect a token has been compromised, revoke it immediately by deleting it from the API Tokens list, then create a new one and update the affected integration.
Next steps
- API Reference — Browse all available API endpoints and schemas (live docs)
- Webhooks — Configure outgoing event notifications
- Adding an integration — General channel setup walkthrough