> For the complete documentation index, see [llms.txt](https://docs.shortcutco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shortcutco.com/developers/concepts/workspaces-and-tokens.md).

# Workspaces and tokens

How a Shortcut workspace, its API tokens, and the people who create them fit together.

After this page you will know what a token can reach, who can create one, how to read a token, and how to keep one safe.

## One workspace per token

A Shortcut workspace is one business: its customers, leads, schedule, crews, estimates, and invoices. Every API token belongs to exactly one workspace and can only ever see and change that workspace's data. There is no way to point a token at another workspace, and an id from another workspace answers `404 resource_not_found`, exactly as if it did not exist.

If you build for several Shortcut businesses, each one creates its own token for you, and you store one token per workspace.

## Who creates tokens

A **company admin** of the workspace creates tokens in **Settings → API & integrations**. Staff without the company admin role do not see the page.

Each token has:

| Setting | What it means                                                                                                             |
| ------- | ------------------------------------------------------------------------------------------------------------------------- |
| Name    | Shown in Settings and returned by `GET /v1/me`. Name it after what uses it: `Website leads`, `Claude`, `QuickBooks sync`. |
| Scopes  | Everything the token can do. See [Scopes](/developers/concepts/scopes.md). Scopes are fixed when the token is created.    |
| Expiry  | 30 days, 90 days, 1 year, or no expiry. Pick the shortest that suits the integration.                                     |

Shortcut shows the full token once, right after **Create**. Copy it straight into your secret store. If it is lost, revoke it and create another.

Tokens are workspace assets. A token keeps working when the admin who created it leaves the company; Settings shows who created each token so another admin can decide what to keep.

## Anatomy of a token

```
scut_<environment>_<token id>_<secret>
scut_live_k7Qm3pX2Lw9a_…
```

| Part        | Example        | What it is                                                                                                                            |
| ----------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Prefix      | `scut`         | Every Shortcut token starts with `scut_`, so secret scanners and `grep` find it. If one turns up in a repository or a log, revoke it. |
| Environment | `live`         | `live` for production workspaces; `dev` for tokens created on Shortcut's dev environment, which look like `scut_dev_…`.               |
| Token id    | `k7Qm3pX2Lw9a` | 12 characters. Settings shows it so you can tell tokens apart; it is not secret on its own.                                           |
| Secret      | 43 characters  | 32 random bytes. Shortcut stores only a hash of it, so nobody at Shortcut can read your token back.                                   |

## Sending a token

Send the token in the `Authorization` header on every request:

```bash
curl https://api.shortcutco.com/v1/me \
  -H "Authorization: Bearer $SHORTCUT_TOKEN"
```

```json
{
  "data": {
    "object": "token",
    "token": {
      "id": "7d1c2f0e-5b8a-4f2e-9c11-2a6b9f3e4d10",
      "name": "Website leads",
      "kind": "api_key",
      "scopes": ["customers:write", "leads:write"]
    },
    "workspace": {
      "id": "3f6a8e2b-1c4d-4e7f-8a9b-0c1d2e3f4a5b",
      "name": "Greenline Lawn Care",
      "timezone": "America/Denver",
      "today": "2026-10-16"
    },
    "rateLimit": { "limit": 600, "remaining": 599, "resetSeconds": 60 }
  }
}
```

`GET /v1/me` needs no scope, so it is the right first call for any new token: it confirms the token works and names the workspace, its timezone, and today's date there.

Shortcut reads the token from the `Authorization` header only. A token in a query string is ignored and the request is answered `401`.

## Keep tokens on servers

A token is a password for the workspace. Keep it in a secret manager or an environment variable on a server you control.

* Never put a token in a web page, a mobile app, or browser JavaScript. The API sends no CORS headers, so browsers refuse cross-site calls anyway; call the API from your server and have your page talk to your server.
* Give each integration its own token, so you can revoke one without breaking the others.
* Grant the fewest scopes the integration needs. A reporting job needs only read scopes.
* Set an expiry, and rotate by creating the new token before revoking the old one.

## Revoking

Revoke a token in **Settings → API & integrations**. The next request with it gets `401 token_invalid`, on the REST API and on the MCP server alike. Revoking cannot be undone.

## API keys and connected apps

A token created in Settings is an **API key**: `GET /v1/me` reports `"kind": "api_key"`. API keys work with the REST API and the MCP server, so the same kind of token powers a server integration, Claude, Claude Code, Cursor, or your own agent. See [Connect Claude](/developers/mcp/connect-claude.md).

## What a token never does

No token can create, list, or revoke tokens, invite staff, change billing, or charge a card directly. Those stay in the app, with a person signed in.