# Permissions
URL: https://docs.fluenta.io/en/docs/permissions

The two permissions of an API token, which routes need each, and why neither exceeds your role.



Here you will see what a token can do with each permission, which routes need
which, and what else the API checks before it accepts a write.

The dashboard is in Spanish; its labels are quoted here as it prints them.

## The two permissions [#the-two-permissions]

| Permission                                    | In the API | When the token has it                         | What it allows                                                                                                             |
| --------------------------------------------- | ---------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| «Leer» (Read)                                 | `read`     | Always                                        | Seeing what you see in Fluenta: the board, the «Programa» (each module's production queue) and the reports                 |
| «Gestionar el Programa» (Manage the Programa) | `program`  | Only if you tick it when you create the token | Creating, changing, moving and deleting OCs (referencias: cuts of a garment), the hourly goals and the reference catalogue |

Permissions are chosen when the token is created and do not change afterwards.
To add «Gestionar el Programa», create a new token.

`GET /me` answers the token's permissions in `connection.scopes`.

## Which permission each route needs [#which-permission-each-route-needs]

Every route in this table sits under
`/v1/external/organizations/{organizationId}`, except the account ones.

| Group             | Routes                                                                                                                                                                                                                                                                                                                        | Permission |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| Account           | `GET /me`, `GET /me/usage`, `GET /organizations`                                                                                                                                                                                                                                                                              | `read`     |
| Reads             | Every `GET` route: organization, plant, boards, «Programa», catalogue, reports and activity                                                                                                                                                                                                                                   | `read`     |
| Delete previews   | `POST /references/{referenceId}/delete-preview`, `POST /catalogue/{templateId}/delete-preview`                                                                                                                                                                                                                                | `read`     |
| «Programa» writes | `POST /references`, `POST /references/from-catalogue`, `PATCH` and `DELETE /references/{referenceId}`, `PATCH …/hold`, `PATCH …/reactivate`, `PATCH …/sacrifice`, `POST …/split`, `POST …/arrive`, `PATCH /modules/{moduleId}/program/order`, `PUT` and `DELETE /modules/{moduleId}/days/{day}/references/{referenceId}/goal` | `program`  |
| Catalogue writes  | `POST /catalogue`, `PATCH` and `DELETE /catalogue/{templateId}`                                                                                                                                                                                                                                                               | `program`  |

In the OpenAPI document, each operation names its permission in
`x-required-scope`. The [reference](/en/docs/reference) shows it per operation.

## When the permission is missing [#when-the-permission-is-missing]

The API answers 403 `INSUFFICIENT_SCOPE` and names the missing permission in
`scope`:

```json
{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "scope": "program",
  "message": "Este token de API no tiene el permiso «Gestionar el Programa». Crea uno nuevo con ese permiso en Configuración."
}
```

Nothing was changed. Create a token with that permission and send the request
again.

## A permission never exceeds your role [#a-permission-never-exceeds-your-role]

A permission gives you nothing your role does not give you in the dashboard.
The API reads your role on every request: if you lose a role in the dashboard,
your tokens lose it on the next request.

Each write needs the same role as its dashboard screen:

| Write                                                                                                                                         | Role it needs          |
| --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| Creating, editing and deleting an OC; adding OCs from the catalogue; writing to the catalogue                                                 | `ADMIN` or `MODERATOR` |
| Reordering the «Programa»; putting an OC on hold, reactivating and splitting it; marking it arrived; the sacrifice write-off; the day's goals | `ADMIN`                |

If your role is not enough, the API answers 403 `ROLE_NOT_ALLOWED`. The body
carries `roles`, the list of roles that can make that change. Nothing was
changed either.

To know what you can do in an organization before you write:

```bash
curl https://api.fluenta.io/v1/external/organizations/42/access \
  -H 'Authorization: Bearer fluenta_live_xxxxxxxxxxxxxxxx'
```

```json
{
  "organizationId": 42,
  "roles": ["ADMIN"],
  "scopes": ["read", "program"],
  "connectorEnabled": true
}
```

## Three checks before a write [#three-checks-before-a-write]

A write goes through only when all three hold:

* The token has `program`. Otherwise, 403 `INSUFFICIENT_SCOPE`.
* Your role makes that change in the dashboard. Otherwise, 403
  `ROLE_NOT_ALLOWED`.
* The organization's plan includes the feature. Otherwise, 403 `PLAN_LIMIT`:
  see [Plans](/en/docs/plans).

Branch on `code`, not on the HTTP status: all three cases answer 403.
[Errors](/en/docs/errors) has the whole list.