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

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

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 shows it per operation.

When the permission is missing

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

{
  "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 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:

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

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

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.

Branch on code, not on the HTTP status: all three cases answer 403. Errors has the whole list.