> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/reference/admin-api/scopes.md).

# Scopes

Every scope a personal access token can hold, which are on by default, and the presets that group them.

A scope is a permission a [personal access token](https://docs.tryterra.co/reference/admin-api/personal-access-tokens.md) holds. Each Admin API endpoint needs one, and a request without it gets `403` with `code: scope_missing`.

| Scope                 | Allows                                                                                                      | Default | Class                           |
| --------------------- | ----------------------------------------------------------------------------------------------------------- | ------- | ------------------------------- |
| `account:read`        | See your account details and environment IDs.                                                               | On      | Account-wide                    |
| `account:write`       | Change your profile and your company's details.                                                             | On      | Account-wide                    |
| `providers:read`      | See which wearables and apps are turned on, and their settings.                                             | On      |                                 |
| `providers:write`     | Turn wearables and apps on or off, and change their sign-in settings.                                       | On      |                                 |
| `destinations:read`   | See where your data is sent, like a webhook or Supabase.                                                    | On      |                                 |
| `destinations:write`  | Add, change or remove where your data is sent.                                                              | On      |                                 |
| `events:read`         | See a log of the data sent to you, without its contents.                                                    | On      |                                 |
| `events:write`        | Send data again.                                                                                            | On      |                                 |
| `connections:read`    | See which of your users have connected.                                                                     | On      |                                 |
| `payloads:read`       | See your users' health data, both what was sent to you and what is stored for them.                         | On      | Sensitive                       |
| `dataconfig:read`     | See which health data fields you get.                                                                       | On      |                                 |
| `dataconfig:write`    | Change which health data fields you get.                                                                    | On      |                                 |
| `scores:read`         | See which scores are turned on, and their settings.                                                         | On      |                                 |
| `scores:write`        | Turn scores on and change their settings.                                                                   | On      |                                 |
| `models:read`         | See the available models and their past results.                                                            | On      |                                 |
| `testdata:write`      | Send made-up health data to where your data goes, from one-off events or test users you can start and stop. | On      |                                 |
| `vantageconfig:read`  | See which Vantage products and markets are turned on, and the products you can turn on.                     | On      |                                 |
| `vantageconfig:write` | Turn Vantage products and markets on or off, and change the Vantage API version.                            | On      |                                 |
| `vantage:read`        | See your Vantage orders and results, including who they are for.                                            | On      | Sensitive                       |
| `keys:read`           | See your API key, the secret values of your data access tokens and the credentials your destinations use.   | On      | Sensitive                       |
| `keys:write`          | Replace your API key. Anything using the old key will stop working.                                         | Off     | Dangerous: access               |
| `tokens:read`         | See the data access tokens in an environment, but not their secret values.                                  | On      |                                 |
| `tokens:write`        | Create and revoke data access tokens in an environment, including other people's.                           | Off     | Dangerous: access               |
| `tokens:admin`        | See and revoke every token across your account, including other people's.                                   | Off     | Dangerous: access, account-wide |
| `entitlements:read`   | See which features your company has access to.                                                              | On      | Account-wide                    |
| `billing:read`        | See your plan, invoices, payment method and usage.                                                          | On      | Account-wide                    |
| `billing:write`       | Change your plan, pay invoices and update payment details.                                                  | Off     | Dangerous: money, account-wide  |
| `team:read`           | See who is on your team.                                                                                    | On      | Account-wide                    |
| `team:write`          | Invite, change or remove team members.                                                                      | Off     | Dangerous: team, account-wide   |

A write scope includes its read scope: a token with `destinations:write` can also call endpoints that need `destinations:read`.

`GET /auth/scopes` returns this list, the classes and the presets as JSON, and needs no token.

## Off by default

Dangerous scopes can spend money, issue or rotate credentials, or change who has access. The approval page leaves them off, and you have to turn each one on. Only account admins can grant them. A token minted in the dashboard cannot hold `tokens:admin`.

## Sensitive scopes

`keys:read`, `payloads:read` and `vantage:read` show data every team member can already see in the dashboard: your API key, stored health data, and Vantage orders and results. They are on by default and labelled on the approval page.

## Account-wide scopes

Account-wide scopes act on your whole account rather than one environment. A token limited to some environments cannot hold them.

## Presets

The approval page offers three presets. You can start from one and change single scopes.

| Preset       | For                                                               | Scopes                                                                      |
| ------------ | ----------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Coding agent | A developer or their coding agent, or an MCP client. The default. | Every scope that is on by default.                                          |
| Read only    | Auditing, onboarding a teammate, or a demo.                       | Every `:read` scope except `keys:read`, `payloads:read` and `vantage:read`. |
| Full access  | Every Admin API scope.                                            | Every scope above, dangerous ones included.                                 |

## Data-plane scopes

`GET /auth/scopes` also lists data-plane scopes, such as `data:read` and `auth:write`. They are for data tokens, created with `POST /environments/{dev_id}/tokens`, and a personal access token cannot hold them. Asking for one at sign-in fails with `invalid_scope`.

## See also

* [Personal access tokens](https://docs.tryterra.co/reference/admin-api/personal-access-tokens.md)
* [Overview](https://docs.tryterra.co/reference/admin-api/overview.md)
