# Scopes

> What each scope lets an app read in version 1, how scopes combine with organizations, and why the write scopes are not available yet.

Source: https://developers-staging.foodpilot.tech/build/scopes

In this page you will learn what each scope unlocks, how a scope and an organization together decide what your app sees, and what changes when a customer consents again.

## The scopes of version 1

| Scope | Lets the app read | App API operations |
|---|---|---|
| (none) | Its own installation and its own billing | `GET /installation`, the [billing](/build/billing) operations |
| `read_organizations` | The organizations it covers | `GET /organizations`, `GET /organizations/{id}` |
| `read_products` | Products and their scores | `GET /products`, `GET /products/{id}`, `GET /products/{id}/scores` |
| `read_ingredients` | Ingredients and their scores | `GET /ingredients`, `GET /ingredients/{id}`, `GET /ingredients/{id}/scores` |
| `read_packagings` | Packagings and their scores | `GET /packagings`, `GET /packagings/{id}`, `GET /packagings/{id}/scores` |
| `read_questionnaires` | The answers to questionnaires | `GET /questionnaires`, `GET /questionnaires/{id}` |

Every path is under `/api/app/v1`. A call whose scope was not granted answers `403` with the problem `scope-missing`.

The questionnaire answers of an entity need two scopes: `read_questionnaires` and the read scope of the entity they belong to (`read_products`, `read_ingredients`, `read_packagings`, or `read_organizations` for an organization's own questionnaire).

## Scopes and organizations

A scope says what kind of data. The organizations chosen at consent say whose. An app only sees the organizations it was granted **and their descendants**, whatever the scope:

- every collection is limited to them;
- an item outside them, or a filter naming an organization outside them, answers `404`;
- `GET /installation` lists the granted organizations (`organizationIds`) and those plus their descendants (`coveredOrganizationIds`).

An organization created after the consent is covered only if it descends from a granted one. Otherwise the administrator consents again.

## Webhooks follow the scopes

A [webhook topic](/build/webhooks/topics) that carries data is delivered only if the installation holds its scope and the event is about a covered organization: `scores/updated` needs `read_products`, `questionnaires/answered` needs `read_questionnaires`. The lifecycle and billing topics need no scope.

## Write scopes

The scopes `write_products`, `write_ingredients`, `write_packagings` and `write_questionnaires` exist in the vocabulary, but version 1 has no write operation, so **they cannot be granted yet**: the marketplace refuses a manifest that asks for one, the consent refuses it, and the token endpoint never issues it. They will come back with write operations added to version 1, each designed and published as its own contract.

## Changing scopes

- **Asking for more.** A new version of the manifest that adds a scope, or a new destination URL, is not applied by itself: the administrator consents again.
- **Asking for less, or consent narrowed.** The change applies at once and the platform sends [`app/scopes_updated`](/build/webhooks/topics).
- **Asking for what you do not use** is the quickest way to be refused at review. Request the scopes your features need and no more.
