# Connect with an API token

A personal API token is a long secret string that you paste into an app's configuration. The app
sends it with every request, and FranchiseSEE treats the request as coming from you. Tokens are
mainly for HQ and IT setups. For everyday questions in Claude or ChatGPT,
[signing in](https://franchisesee.com/docs/ai/sign-in.md) is quicker.

## When to choose a token

- **Managing locations and users.** The admin server, which creates, updates and deletes
  locations, districts, categories, location groups and users, accepts tokens only.
- **Apps that can't sign in.** GitHub Copilot, Claude Desktop through `mcp-remote`, and any client
  that takes a header rather than opening a sign-in page.
- **Setups IT manages.** A config file rolled out to a team, or a repository's Copilot coding
  agent, holds a token rather than one person's sign-in.
- **Scripts and CI.** A job that runs on its own. For these, the [REST API](#for-scripts-prefer-the-rest-api)
  is usually the better fit.

## Create a token

1. Sign in to FranchiseSEE.
2. Open the profile menu, choose **User settings**, then **API tokens**.
3. Name the token after the app or job that will use it, such as "Copilot – reporting".
4. Choose its permissions:
   - `read` is all the reporting server needs.
   - For the admin server, add `create`, `update` or `delete` for the changes you want it to make.
5. Choose how long it lasts: 30 days, 90 days, a year, or (HQ only) never.
6. Create it, and copy the token straight away. It is shown only once.

A token never does more than your account can: its access is the overlap of your account's
permissions and the token's. See [Token permissions](https://franchisesee.com/docs/api/getting-started.md#token-permissions).

Then set up your app: [Token clients](https://franchisesee.com/docs/ai/token-clients.md) has the configuration for GitHub
Copilot, Claude Code, Claude Desktop and other clients.

### Who can create tokens

- **HQ (franchisor) accounts** with the *Manage API tokens* permission create tokens with any
  permissions and any lifetime, including tokens that never expire, for integrations and CI that
  run unattended.
- **Franchisee accounts** create tokens only while HQ has *Let franchisees create personal tokens*
  turned on. A franchisee token is always read-only, always expires after 30 days, 90 days or a
  year, and works with the reporting server and the REST API but not the admin server. If HQ turns
  the switch off, every franchisee token is deleted and stops working. See
  [Brand switches for HQ admins](https://franchisesee.com/docs/ai/data-scope-and-permissions.md#brand-switches-for-hq-admins).

## The admin server

```text
https://app.franchisesee.com/mcp/admin
```

The admin server is for HQ accounts: it refuses a franchisee token before any tool runs. It makes
changes, so each one needs the matching permission on your account as well as a token with
`create`, `update` or `delete`:

| Account permission | Lets you |
|--------------------|----------|
| Manage Locations | Create, update and delete locations, districts, categories and location groups; bulk district assignment; replace a location's groups |
| Manage Users | Update and delete users; add or replace users' location groups; bulk user-to-group assignment |

Without the permission, the tool is refused and your AI app reports that the action wasn't
authorized. The admin server never accepts a sign-in. The reporting server takes the same tokens,
with `read`:

```text
https://app.franchisesee.com/mcp/reporting
```

The [MCP tool reference](https://franchisesee.com/docs/ai/tools) lists every tool on both servers.

## Keep a token safe

> [!WARNING]
> Anyone who has a token can read your FranchiseSEE data as you, and an HQ token with write
> permissions can change it. Never commit a token to a repository or paste it into a shared file.

- Give each app or job its own token with only the permissions it needs, so you can revoke one
  without breaking the others.
- Keep tokens in your app's secret storage, an environment variable or a secrets manager. The
  [Token clients](https://franchisesee.com/docs/ai/token-clients.md) examples keep the token out of the config file where the app
  allows it.
- Give an unattended job a token that expires, and replace it before it does, unless it truly
  must never stop.

## Revoke a token

Open the profile menu, choose **User settings**, then **API tokens**, and delete the token. Every
app using it stops working at once. Delete any token you no longer use.

## For scripts, prefer the REST API

For a script that reads or changes data on a schedule, the [REST API](https://franchisesee.com/docs/api/getting-started.md)
is usually a better fit than MCP: plain HTTP requests with stable JSON answers. It takes the same
tokens.

## Something wrong?

See [Troubleshooting: API tokens](https://franchisesee.com/docs/ai/troubleshooting.md#api-tokens).