# Tokens and AI apps

Your customers’ scripts and AI apps reach their account with a token. An AI app can also sign in through your product.

Your customers sign in only through your app, so a script can’t sign in as them. A token stands in for the person who made it, in one workspace of one account.

## The switches

Four switches under **Developers**, all off until you turn them on. Each needs the one before it. When on:

- **Tokens** · `tokens`: The embed has a tokens page, and tokens made for the account work at all.
- **MCP** · `mcp`: Tokens work with AI apps too, which run the account’s published workflows as tools.
- **MCP building** · `mcpBuild`: An AI app can also create and change workflows.
- **MCP sign-in** · `mcpSignIn`: People connect AI apps by signing in through your product, with no token. See [Let customers sign in AI apps](https://docs.gorunner.io/embed/ai-app-sign-in).

## The customer’s page

With **Tokens** on, the embed has a page named **API tokens**, or **MCP** while the **MCP** switch is on. With **Tokens** off, a person whose AI apps signed in keeps the page, as **MCP**, only to disconnect them.

- **New token**: A **Name**; **It may**: **Read only**, **Draft and run**, **Draft, run and publish** or **Custom**; and **Expires**: 30 days, 90 days or 1 year. The token shows once.
- **Connect an AI app**: Sets up Claude Code, Cursor, VS Code or another app that supports MCP, with this account’s address.
- **Connected apps**: The apps the person signed in, each with **Disconnect**. A paused one says which switch is off.
- **Revoke**: In a token’s menu. “Apps using this token stop working at once.”

Only editors make and revoke tokens, and not while the account is suspended. Operators and viewers see the list. A preview can’t make one, and a workspace holds at most 25 working tokens.

## What a token can do

- **One workspace**: The one it was made in, in one account. It never reaches another.
- **No more than its maker**: Narrowed to the maker’s role and every switch that is off for them. A choice beyond that can’t be picked.
- **Judged on every request**: It stops while `tokens` is off for the installation, the account or the token. While the account is suspended, it can only read.
- **Never**: Makes or revokes tokens, or reaches the assistant.

## When it stops working

A token ends for good when its maker leaves the account or stops being an editor, when the account or workspace is deleted, when it is revoked or expires, and when the partner key that made it is revoked. Rotating that key doesn’t stop it. A restored account starts with no tokens.

- 401 `TOKEN_ENDED`

  It ended. `details.reason` is `access_removed`, `role_changed`, `account_deleted`, `workspace_deleted`, `revoked` or `expired`.

- 403 `FEATURE_OFF`

  A switch is off; `details.switch` names it.

- 403 `TOKEN_SURFACE_OFF`

  It wasn’t made to work here: the API, or AI apps.

- 401 `UNAUTHORIZED`

  No such token.

## Use a token

It works with the [API](https://docs.gorunner.io/api), at your installation’s address:

```bash
curl https://automations.example.com/api/workflows \
  -H "Authorization: Bearer grt_…"
```

With an AI app, use `https://automations.example.com/mcp/tools`, or `/mcp/build` while **MCP building** is on, with the token in `Authorization: Bearer grt_…`. **Connect an AI app** shows the exact address. `/mcp/tools` lists no workflow while the account’s switches don’t let its people run workflows. The steps for each app are in [AI apps](https://docs.gorunner.io/mcp).

**What about AI apps that only sign in?**

ChatGPT, Claude and Raycast connect only by signing in. Without **MCP sign-in**, the page says so, and they can’t connect. With it, each account has its own address, `…/mcp/embed/<account>/build` (or `/tools`). See [Let customers sign in AI apps](https://docs.gorunner.io/embed/ai-app-sign-in).

## Tokens from your server

[Make a token](https://docs.gorunner.io/embed/api/tokens/create-token) makes one for an account, for your own automation or to hand to the customer. It is made “by your app”, under the same rules.

- `access` or `scopes`: What it may do: `read`, `run` or `build`, or scopes one by one. One of them is required. Scopes that aren’t exactly one of those levels read back as `access: custom`.
- `surfaces`: Where it works: `api`, `mcp` (needs **MCP**), or both. Default `["api"]`. An empty list is refused.
- `expiresInDays`: 7 to 365. Default 90.
- `turnOff`: Switches off for this token alone.

The answer carries the token once, as `raw`. It takes no `Idempotency-Key`, so no stored answer keeps the token: a retry makes a second one, which you can list and revoke.

## Related

- [Let customers sign in AI apps](https://docs.gorunner.io/embed/ai-app-sign-in): ChatGPT, Claude and other AI apps, through your sign-in
- [Switches](https://docs.gorunner.io/embed/switches): Every switch and its default
- [MCP](https://docs.gorunner.io/mcp): Set up each AI app

Source: https://docs.gorunner.io/embed/tokens-and-ai-apps