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.

Embed · Self-hosted with an Embed license

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.

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.

401TOKEN_ENDED
It ended. details.reason is access_removed, role_changed, account_deleted, workspace_deleted, revoked or expired.
403FEATURE_OFF
A switch is off; details.switch names it.
403TOKEN_SURFACE_OFF
It wasn’t made to work here: the API, or AI apps.
401UNAUTHORIZED
No such token.

Use a token

It works with the 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.

Tokens from your server

Make a 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.

Checked against 12d85b3b