Skip to content
Docs
Docs / AI & Connectors / API token

Connect with an API token

MD View as MarkdownPlain text version of this page
Open in ClaudeAsk questions about this page Open in ChatGPTAsk questions about this page

Use a personal API token for the admin server, apps that can't sign in, scripts and IT-managed setups.

On this page

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

Then set up your app: Token clients 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.

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 lists every tool on both servers.

Keep a token safe

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