Access tokens

Create a token

Tokens live on your profile, so they follow you across every workspace you belong to. You create one from a workspace on the Pro or Business plan, and it works in every workspace you belong to that is on one of them.

1. Open the menu in the top-right corner of the dashboard and click Profile, then find the Developer section.
2. Click Access tokens, then New.
3. Give the token a name you will recognise later, such as the tool or machine that will use it.
4. Tick the scopes it needs.
5. Optionally tick the workspaces it may reach. Leave this blank to allow every workspace you belong to.
6. Click Create.

Scopes

Each tool requires a scope, or accepts any one of a few (the node-type reference needs none). Grant only the scopes your agent needs.

• read:knowledge, write:knowledge, delete:knowledge
• read:storage, write:storage, delete:storage
• read:flow, run:flow, write:flow, delete:flow, publish:flow, deploy:flow
• read:conversations, read:conversations_pii, debug:conversations
• read:leads, write:leads
• read:workforce, write:workforce
• read:inbox, write:inbox

Read and run scopes suit an agent that answers questions and tries flows. Add write, publish, or deploy scopes only when the agent needs to change things. The Tool catalog lists the scope every tool requires.

A token never does more than its owner can in the dashboard. A member's token reads and runs; a member who is a builder can also change, publish and deploy flows and change tables, and a knowledge manager can change knowledge bases. Owners, managers and admins can do all of these.

Two scopes gate sensitive conversation data: read:conversations_pii reveals the details a visitor gave during a conversation, including the values the flow collected and the contact's email and phone, and debug:conversations exposes a run's raw step trace. Grant them deliberately.

Transcripts follow the same rule as the dashboard: a workspace owner, manager or admin reads them, and a member gets each conversation's details without its messages, whatever scopes the token holds.

read:workforce shows your teams, the people on them, the seats everyone holds, and time off. write:workforce creates, changes and deletes teams, sets how each team works the inbox (how conversations reach its members, what happens after hours, its service targets and conversation limits), keeps your disposition lists, gives people agent seats, which your plan bills beyond its included number, and sets time off. Each person can do through a token only what they can do in the dashboard: owners and managers create and delete teams, pick their members and supervisors, and give seats; admins change the rest of a team and how it works; anyone sets their own time off, and a team supervisor their team members'. People's emails and roles are shown only to owners, managers and admins.

The team list is also open to read:inbox and read:leads, since the inbox and leads tools name teams. read:inbox shows your support agents' statuses, the waiting queue, conversations close to missing a service target, and the history of closes, declines, escalations and missed targets, along with the support report. write:inbox works conversations: it sets your own status, closes and declines conversations, marks one as waiting on the customer, records how a closed conversation ended, and finishes your wrap-up. Owners, managers and admins also set a conversation's priority and mark contacts VIP with it. Only owners, managers and admins can grant write:inbox.

read:leads includes each lead's name, email and phone, since that is what a lead is. Grant it only to agents that should see your prospects' contact details.

Restrict to workspaces

By default a token can reach every workspace you belong to, and each call names the one it runs in. If you want a token pinned to specific workspaces, tick them when you create it. The list only ever offers workspaces you are a member of, and if your membership is removed the token loses that workspace with it.

Revoke a token

Open the token from the list and choose Revoke. It stops working immediately. The row stays so you can see when it was last used, but the token can no longer authenticate. Revoke a token the moment it is no longer needed or might have leaked.

Resetting your password through Forgot password revokes every token on your account and sends you an email to say so. Create new tokens for the agents you still use. Changing your password while signed in leaves your tokens working.

Keep tokens safe

• Treat a token like a password. Anyone who has it can act as you, within its scopes.
• Give each agent or machine its own token, so you can revoke one without affecting the others.
• Grant the narrowest scopes and workspaces that get the job done.
• Store it in your agent's secret configuration, never in shared files or version control.