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

# Scopes

Token permissions required for each operation

Scopes control what actions a JWT token is allowed to perform. Each API endpoint requires a specific scope — if the token does not include that scope, the request is rejected.

## Available Scopes

| Scope          | What It Allows                                                                                                        |
| -------------- | --------------------------------------------------------------------------------------------------------------------- |
| `ReadPeople`   | Read operations — retrieving, listing, filtering, and querying relationships for both people and records              |
| `WritePeople`  | Write operations — creating, updating (PUT/PATCH), and deleting both people and records. Also covers consent updates. |
| `WriteRecords` | Creating new records in a stack                                                                                       |

## Scope by Operation

Here's a quick reference for which scope you need:

| Operation                      | People        | Records        |
| ------------------------------ | ------------- | -------------- |
| **Create**                     | `WritePeople` | `WriteRecords` |
| **Get** (by ID or external ID) | `ReadPeople`  | `ReadPeople`   |
| **List** (paginated)           | `ReadPeople`  | `ReadPeople`   |
| **Filter**                     | `ReadPeople`  | `ReadPeople`   |
| **Update** (PUT)               | `WritePeople` | `WritePeople`  |
| **Partial Update** (PATCH)     | `WritePeople` | `WritePeople`  |
| **Delete**                     | `WritePeople` | `WritePeople`  |
| **Get Related Entities**       | `ReadPeople`  | `ReadPeople`   |
| **Update Consent**             | `WritePeople` | —              |

{% hint style="info" %}

* A single token can carry multiple scopes. For example, a token with both `ReadPeople` and `WritePeople` can perform all people and records operations except creating new records.
* `WriteRecords` is only used for **creating** records. Updating and deleting records requires `WritePeople`.
* `ReadPeople` covers both people and records — there is no separate "ReadRecords" scope.
  {% endhint %}