Agent tokens
Create, scope, rotate and revoke the integration tokens that Claude Code, agents and Excel use to reach your workspace, and keep them safe.
An agent token is a secret string that lets something outside sanda reach one workspace. The console calls it an integration token, and it always begins with bat_. You paste it into a client once, and the client sends it with every request.
Use a token when a person is not there to sign in: Claude Code, the Claude API, an agent harness of your own, or an Excel workbook that refreshes on a schedule. Where a client can sign a person in with OAuth, prefer that, because there is no secret to store. See connect other MCP clients.
Where a token works
| Where | How it is sent | Editions |
|---|---|---|
The MCP address, https://console.sanda-os.com.au/api/mcp |
Authorization: Bearer bat_... |
Every edition |
The Excel and Power BI feed, https://console.sanda-os.com.au/api/odata/ |
As the password of a Basic credential, or as a bearer header | Every edition |
A token cannot sign in to the console. It can do what the MCP tools and the feed do, and nothing else.
You can create and revoke tokens on any edition. The sanda search tools answer only on an edition that includes sanda search.
Create a token
Only an owner or admin can create tokens.
- Open Settings · Integrations. In the console, go to Settings and choose Integrations.
- Open the New token form. Press New token.
- Name the token. Under Name, say what will hold it, for example "Finance agent" or "Board pack workbook". A name is up to 80 characters. The name is how you will tell your tokens apart later.
- Tick only what it needs. Every token can ask questions. Each switch beyond that is off until you turn it on. See the table below.
- Set an expiry. Under Expires, choose Never, 30 days, 90 days or One year.
- Press Create token. sanda shows the token once, with the feed address for Excel and Power BI and ready-made entries for Claude Code, the Claude API and curl.
- Copy it now. sanda keeps only a hash and cannot show it again. If you lose it, create another.
A workspace can hold 25 live tokens at once. Revoke one before creating another.
The switches
Every token can ask questions of the fluid (query:run). The switches add to that. The scope is the permission's name in the tool reference and on the consent screen.
| Switch | Scope | What it allows |
|---|---|---|
| May run its own SQL | sql:run |
A read-only SELECT of its own, through the same read-only role, when the fluid cannot express a question |
| May run and commit its own SQL | sql:write |
One statement at a time as the warehouse's builder role, committed at once. Reads every landing table and writes only the derived schema. No undo |
| May write the fluid | fluid:write |
Put tables on the map, define metrics, dimensions, filters and relationships, and accept or remove proposals. Live at once |
| May see connections and warehouses | workspace:read |
What is connected, when it last synced, how full each warehouse is. Never a credential |
| May start a sync | workspace:manage |
Run a connection now instead of on its schedule |
| May load rows into the warehouse | warehouse:write |
Land tables of its own rows as raw.csv__.... It cannot touch a table a sync landed |
| May define views and procedures | warehouse:model |
Build views, materialized views and procedures in the derived schema, run them and put views on the map, on your compute |
| May add rows to intake tables | warehouse:append |
Append rows to tables an owner or admin has opened for intake, and nothing else |
| May manage search services | search:manage |
Create, rebuild and remove sanda search services |
| May email reports | reports:deliver |
Schedule report deliveries, change or pause them and send one now |
The full effect of each, including which tools it allows, is in scopes. A switch that reaches beyond asking questions is a decision worth making on purpose. Leave every switch off unless the client's job needs it.
What decides what a token can do
The switches are the ceiling. Four other things can lower it:
- Who made it. The privileged scopes (everything above except May see connections and warehouses and May add rows to intake tables) last only as long as the person who made the token is still an owner or admin. If they are demoted, sanda stops honouring those switches and the token's row is marked "permissions inactive". Everything else it holds still works.
- Whether that person is still here. A token stops working when the person who created it leaves the workspace. Its row is marked "maker left" until someone clears it away.
- The workspace's state. When a workspace is closed it becomes read-only, and every token is limited to asking questions and seeing connections.
- The edition. The search tools need Standard or Enterprise.
See your tokens
Settings · Integrations lists every live token, and the apps members have connected by approving sanda's consent screen, in one list. Any member can see every token. Owners and admins also see every member's connected apps, and everyone else sees their own. Each row shows:
- the token's name and its last six characters, which is enough to match it against the string in a client's configuration and not enough to use it;
- who made it, when, when it was last used ("never used" if it has not been), and when it expires;
- one label for each thing it may do beyond questions.
| Label | Scope |
|---|---|
| fluid only | Nothing beyond asking questions |
| may run SQL | sql:run |
| commits SQL | sql:write |
| writes the fluid | fluid:write |
| sees connections | workspace:read |
| starts syncs | workspace:manage |
| loads rows | warehouse:write |
| appends rows | warehouse:append |
| defines views | warehouse:model |
| manages search | search:manage |
| emails reports | reports:deliver |
To see what a token has been doing, open Intelligence · Agents. It shows each credential's permissions in full sentences, and the calls it has made. See MCP and agents.
Rotate a token
A token cannot be changed in place, and sanda cannot show you an old one. To rotate:
- Create a new token with the same name (add a date, such as "Finance agent, October") and the same switches.
- Put it in every place that used the old one. For an Excel workbook, follow change or clear the saved token.
- Check that the new token is in use. On Intelligence · Agents, or in the token list, the new one shows a "last used" time once a client has called with it.
- Revoke the old token.
Setting an expiry when you create a token turns rotation into a habit. A token that expires in 90 days needs replacing every 90 days, and a token nobody remembers stops working on its own.
Revoke a token
Press Revoke on the token's row. Owners and admins can revoke any token. Anyone can revoke a token they made themselves.
Revoking takes effect at once: the next call the token makes fails with a 401. The token disappears from the list, and sanda keeps a record of its creation and revocation in the audit trail. There is no undo, and no way to bring the same token back. Create a new one instead.
A connected app, such as Claude, is disconnected from the same list with Disconnect.
Keep tokens safe
- Treat a token like a password. Anyone who holds it can do whatever its switches allow, as your workspace, until it is revoked.
- One token for each client. When something goes wrong you can revoke that one and leave the others working. Name it after what holds it.
- Grant the least. A workbook needs no switches at all. A reporting agent rarely needs to write the fluid.
- Set an expiry. Choose 30 or 90 days for anything you would have to remember to review.
- Keep it out of chat, tickets and source control. The
bat_prefix is there so that secret scanners recognise a leaked token, and it is worth switching scanning on for your repositories. - Keep it out of URLs. Send it in a header, or as a Basic password in Excel. A URL is copied into logs and browser history.
- If one leaks, revoke it first. Then open Intelligence · Agents and read the Calls tab for what it did, and create a replacement.
- Ask for approval on the risky actions. An owner or admin can make committed SQL, dropped views, dropped search services and emails to outside addresses wait for a person, even for a token that holds the permission. See permissions and approvals.
Next steps
Something unclear or out of date? Tell us, and we will fix the page.