# Permisos
URL: https://docs.fluenta.io/docs/permissions

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 [#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 [#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](/docs/reference) lo muestra por operación.

## Si falta el permiso [#si-falta-el-permiso]

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

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

## Un permiso nunca supera tu rol [#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:

```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
}
```

## Tres revisiones antes de escribir [#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](/docs/plans).

Decide por `code`, no por el estado HTTP: los tres casos responden 403.
[Errores](/docs/errors) tiene la lista completa.