# Getting started

The FranchiseSEE REST API lets your own systems read performance data and manage locations,
districts, location groups and users. Every request is authenticated with a bearer token, and every
response is JSON.

## Base URL

All endpoints live under one host:

```text
https://app.franchisesee.com/api
```

Resource endpoints are versioned under `/api/v1` (for example `/api/v1/locations`). Two endpoints sit
outside the version prefix: `GET /api/user` and `POST /api/custom-metrics`.

## Create an API token

1. Sign in to FranchiseSEE.
2. Open the profile menu in the top right, choose **User settings**, then choose **API tokens**.
3. Name the token, choose its permissions and how long it lasts, and create it.
4. Copy the token straight away. It is shown only once.

Each token belongs to your account and acts as you. Keep it as secret as a password.

> [!NOTE]
> Who sees **API tokens** depends on your account:
>
> - **HQ (franchisor) accounts** with the *Manage API tokens* permission can create tokens with any
>   permission, including tokens that never expire.
> - **Franchisee accounts** can create tokens only when their brand has AI connections on and has
>   turned on *Let franchisees create personal tokens*. A franchisee token is always read-only and always expires (after 30
>   days, 90 days or a year).

## Token permissions

When you create a token you choose which of four permissions it carries:

| Permission | Allows |
|------------|--------|
| `read` | View resources and run reports: every `GET` endpoint and the reporting MCP server |
| `create` | Create new resources (`POST` create endpoints) |
| `update` | Change existing resources (`PATCH` and `PUT`, including the bulk and sync endpoints) |
| `delete` | Permanently remove resources (`DELETE` endpoints) |

`GET /api/user` is the one exception: any authenticated token may call it, whatever its
permissions. Use it to confirm which account a token acts as.

A token can never do more than your account can. Its effective access is the **overlap** of your
own account permissions and the permissions you gave the token:

- A full administrator can still create a `read`-only token to hand to a reporting integration.
  That token can only read, even though the account can write.
- Giving a token `create` does nothing if the account that owns it can't create that kind of
  resource.

The token screen shows a live **"What this token will be able to do"** preview before you create a
token, and you can change a token's permissions later.

## Make your first request

Send the token in the `Authorization` header with the `Bearer` scheme, and ask for JSON:

```bash
curl https://app.franchisesee.com/api/user \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"
```

A successful call returns the account the token acts as:

```json
{
  "data": {
    "id": "6e2b9d41-8c7a-4f3e-b1d5-9a0c2e4f6b81",
    "first_name": "Jordan",
    "last_name": "Rivera",
    "email": "jordan.rivera@example.com",
    "perspective": "franchisor",
    "location_id": null,
    "has_sso_auth": true,
    "roles": ["franchisor_admin"],
    "created_at": "2025-03-14T15:22:08.000000Z",
    "updated_at": "2026-10-02T09:41:55.000000Z"
  }
}
```

Then list your locations:

```bash
curl "https://app.franchisesee.com/api/v1/locations?page[size]=25" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"
```

Collections are paginated, and most can be filtered, sorted and expanded with related records. See
[Querying collections](https://franchisesee.com/docs/api/querying.md).

## What a token can see

A token sees exactly what its owner sees when they sign in:

- **HQ accounts** see every location in the brand.
- **Franchisee accounts** see only the locations assigned to them. Asking for any other location
  returns `403 Forbidden`.

Data never crosses brands: every token is scoped to its owner's organization.

## Rate limits

The `/api/v1` endpoints allow **60 requests per minute** per user. Every token you own shares that
allowance, so give busy integrations their own user account if they need their own limit. Going
over returns
`429 Too Many Requests` with a `Retry-After` header. See [Errors](https://franchisesee.com/docs/api/errors.md#429-too-many-requests).

## Keep tokens safe

- Never share a token or commit it to version control.
- Keep tokens in environment variables or a secrets manager, not in code.
- Give each integration its own token with only the permissions it needs, so you can revoke one
  without breaking the others.
- Rotate tokens regularly, and delete any you no longer use.
- Always call the API over HTTPS.