Permisos

Los dos permisos de un token de API, qué rutas pide cada uno y por qué ninguno supera tu rol.

Aquí verás qué puede hacer un token con cada permiso, qué rutas piden cuál y qué más revisa la API antes de aceptar una escritura.

Los dos permisos

Permiso	En la API	Cuándo lo tiene el token	Qué permite
«Leer»	`read`	Siempre	Ver lo que tú ves en Fluenta: el tablero, el Programa y los reportes
«Gestionar el Programa»	`program`	Solo si lo marcas al crear el token	Crear, cambiar, mover y borrar OC, las metas por hora y el catálogo de referencias

Los permisos se eligen al crear el token y no cambian después. Para sumar «Gestionar el Programa», crea un token nuevo.

GET /me responde los permisos del token en connection.scopes.

Qué permiso pide cada ruta

Todas las rutas de esta tabla van bajo /v1/external/organizations/{organizationId}, salvo las de cuenta.

Grupo	Rutas	Permiso
Cuenta	`GET /me`, `GET /me/usage`, `GET /organizations`	`read`
Lecturas	Todas las rutas `GET`: organización, planta, tableros, Programa, catálogo, reportes y actividad	`read`
Vistas previas de borrado	`POST /references/{referenceId}/delete-preview`, `POST /catalogue/{templateId}/delete-preview`	`read`
Escrituras del Programa	`POST /references`, `POST /references/from-catalogue`, `PATCH` y `DELETE /references/{referenceId}`, `PATCH …/hold`, `PATCH …/reactivate`, `PATCH …/sacrifice`, `POST …/split`, `POST …/arrive`, `PATCH /modules/{moduleId}/program/order`, `PUT` y `DELETE /modules/{moduleId}/days/{day}/references/{referenceId}/goal`	`program`
Escrituras del catálogo	`POST /catalogue`, `PATCH` y `DELETE /catalogue/{templateId}`	`program`

En el documento OpenAPI, cada operación nombra su permiso en x-required-scope. La referencia lo muestra por operación.

Si falta el permiso

La API responde 403 INSUFFICIENT_SCOPE y nombra el permiso que falta en 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."
}

No se cambió nada. Crea un token con ese permiso y repite la solicitud.

Un permiso nunca supera tu rol

Un permiso no te da nada que tu rol no te dé en el panel. La API lee tu rol en cada solicitud: si pierdes un rol en el panel, tus tokens lo pierden en la siguiente solicitud.

Cada escritura pide el mismo rol que su pantalla del panel:

Escritura	Rol que pide
Crear, editar y borrar una OC; agregar OC del catálogo; escribir en el catálogo	`ADMIN` o `MODERATOR`
Reordenar el Programa; pausar, reactivar y dividir una OC; marcar que llegó; el descuento por sacrificio; las metas del día	`ADMIN`

Si tu rol no alcanza, la API responde 403 ROLE_NOT_ALLOWED. El cuerpo trae roles, la lista de roles que sí pueden hacer ese cambio. Tampoco se cambió nada.

Para saber qué puedes hacer en una organización antes de escribir:

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
}

Tres revisiones antes de escribir

Una escritura pasa solo si se cumplen las tres:

El token tiene program. Si no, 403 INSUFFICIENT_SCOPE.
Tu rol hace ese cambio en el panel. Si no, 403 ROLE_NOT_ALLOWED.
El plan de la organización incluye la función. Si no, 403 PLAN_LIMIT: mira Planes.

Decide por code, no por el estado HTTP: los tres casos responden 403. Errores tiene la lista completa.