# 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](https://docs.sanda-os.com.au/mcp/connect-other-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.

:::steps
1. **Open Settings · Integrations.** In the console, go to **Settings** and choose **Integrations**.
2. **Open the New token form.** Press **New token**.
3. **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.
4. **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.
5. **Set an expiry.** Under **Expires**, choose **Never**, **30 days**, **90 days** or **One year**.
6. **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.
7. **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](https://docs.sanda-os.com.au/reference/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](https://docs.sanda-os.com.au/mcp).

## Rotate a token

A token cannot be changed in place, and sanda cannot show you an old one. To rotate:

:::steps
1. **Create a new token** with the same name (add a date, such as "Finance agent, October") and the same switches.
2. **Put it in every place that used the old one.** For an Excel workbook, follow [change or clear the saved token](https://docs.sanda-os.com.au/odata/excel#change-or-clear-the-saved-token).
3. **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.
4. **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](https://docs.sanda-os.com.au/mcp/permissions#approvals).

## Next steps

:::links
- [Permissions and approvals](https://docs.sanda-os.com.au/mcp/permissions): Decide what an agent may do, and who has to agree first.
- [Connect Excel](https://docs.sanda-os.com.au/odata/excel): Use a token as the password of a Basic credential.
- [Scopes](https://docs.sanda-os.com.au/reference/scopes): What every switch allows and which tools it gives.
:::