# Tokens y alcances

> Crea tokens de la API en Ajustes → API, elige los alcances correctos y envía el token en el header Authorization.

URL: https://docs.proteside.com/es/docs/api/authentication

Toda llamada a la API (excepto el documento OpenAPI) necesita un token. El token pertenece a la **organización**, no a
un usuario ni a una tienda: vale para todas las tiendas de la organización y sigue funcionando si quien lo creó deja el
equipo.

## Crear un token
Solo el **propietario de la organización** crea y revoca tokens. Los demás roles ven el aviso "Solo el propietario de
la organización puede gestionar tokens." en lugar de la lista.

### Abre la pantalla de tokens
En el selector de tiendas, elige una tienda de la organización que va a usar el token. Después abre
**Ajustes → API**. El token se crea para la organización de la tienda seleccionada.

### Haz clic en Nuevo token
Haz clic en **Nuevo token** en la esquina superior derecha.

### Ponle un nombre
Completa **Nombre** con algo que identifique la integración, por ejemplo "CI de producción" o "SIEM". El nombre acepta
hasta 80 caracteres y aparece en la lista y en la auditoría.

### Marca los alcances
En **Alcances**, marca solo lo que necesita la integración. Los atajos **solo lectura**, **todos** y **ninguno**
ayudan a empezar. Es obligatorio marcar al menos uno. Los alcances no se pueden cambiar después: para cambiarlos, crea
otro token.

### Elige la vigencia
En **Vigencia**, elige **Sin vencimiento**, **30 días**, **90 días** o **365 días**. Pasado el plazo, el token empieza
a responder `401 Token expired`.

### Copia el token
Haz clic en **Crear token**. En la ventana **Copia el token ahora**, haz clic en **Copiar** y guarda el token en una
bóveda de secretos antes de hacer clic en **Listo**.

> **El token aparece una sola vez**
>
> Proteside guarda solo un hash del token. Si cierras la ventana sin copiarlo, no hay forma de recuperarlo: revócalo y
> crea otro.

*Imagen: La lista muestra el prefijo de cada token, los alcances, el último uso y el estado (Activo, Vencido o Revocado).*

> **Propietario de la tienda no es lo mismo que propietario de la organización**
>
> La pantalla muestra el botón **Nuevo token** a quien es propietario de la tienda seleccionada, pero la creación exige
> ser propietario de la **organización**. Si ves el error "Solo el propietario de la organización puede gestionar
> tokens." al hacer clic en **Crear token**, pide al propietario de la organización que cree el token.

## Usar el token
El token tiene el formato `ps_live_` + 24 caracteres + `_` + 32 caracteres (65 en total). Envíalo en el header
`Authorization` de cada solicitud:

```bash
curl -s "https://app.proteside.com/api/v1/stores" \
  -H "Authorization: Bearer ps_live_TU_TOKEN"
```

Los primeros 32 caracteres (`ps_live_` + 24) son el **prefijo**: es lo que aparece en la columna **Prefijo** de la
lista y en los registros de auditoría de las acciones hechas por la API (`api:ps_live_TU_PREFIJO`).

Cuando el token falla, la API responde `401` con el header `WWW-Authenticate: Bearer realm="proteside-api"` y uno de
estos mensajes:

| `message`                           | Causa                                                       |
| ----------------------------------- | ----------------------------------------------------------- |
| `Missing or malformed bearer token` | Header ausente, sin `Bearer` o token con formato incorrecto |
| `Invalid token`                     | Token inexistente o revocado                                |
| `Token expired`                     | Plazo de vigencia vencido                                   |

La columna **Último uso** se actualiza como máximo una vez por minuto por token.

## Alcances
Cada endpoint exige **exactamente un** alcance. No hay jerarquía: `stores:write` no incluye `stores:read`, así que una
integración que crea y después consulta tiendas necesita los dos. Sin el alcance, la respuesta es
`403 insufficient_scope`.

| Alcance            | Qué habilita                                                                                                                                  |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `stores:read`      | `GET /stores`, `GET /stores/{id}`, `GET /stores/{id}/status`, `GET /stores/{id}/pages`                                                        |
| `stores:write`     | `POST /stores`, `PATCH /stores/{id}`, `DELETE /stores/{id}` (suspende), `POST /stores/{id}/rotate-key`                                        |
| `pages:write`      | `POST /stores/{id}/pages`                                                                                                                     |
| `scripts:read`     | `GET /scripts` y `GET /rules`                                                                                                                 |
| `scripts:review`   | `POST /scripts/{id}/authorize`, `POST /scripts/{id}/block`                                                                                    |
| `rules:write`      | `POST /rules`, `PATCH /rules/{id}`, `DELETE /rules/{id}`, `DELETE /rules?id=`                                                                 |
| `policies:read`    | `GET /policies`, `POST /policies/{id}/simulate`                                                                                               |
| `policies:write`   | `POST /policies`, `PATCH /policies/{id}`, `DELETE /policies/{id}`, `POST /policies/{id}/apply`                                                |
| `alerts:read`      | `GET /alerts`, `GET /alerts/{id}`                                                                                                             |
| `alerts:write`     | `PATCH /alerts/{id}` (resolver y reabrir)                                                                                                     |
| `reports:read`     | `GET /reports/pci`, `GET /reports/pci/snapshots`, `GET /reports/pci/snapshots/{id}`, `GET /reports/pci/schedule`                              |
| `reports:generate` | `POST /reports/pci/schedule`, `DELETE /reports/pci/schedule`; también se exige junto con `reports:read` en `GET /reports/pci?regenerate=true` |
| `webhooks:manage`  | Todos los endpoints `/webhooks`, incluidas la lectura y la prueba                                                                             |
| `orgs:manage`      | `GET /organizations`, `POST /organizations` y el uso de `org_id` para actuar en una organización hija ([Partners](https://docs.proteside.com/es/docs/api/partners))            |
| `usage:read`       | `GET /organizations/{id}/usage`                                                                                                               |

El atajo **solo lectura** marca `stores:read`, `scripts:read`, `policies:read`, `alerts:read`, `reports:read` y
`usage:read`.

> **Listar reglas exige scripts:read**
>
> El spec OpenAPI describe `stores:read` como el alcance de lectura de reglas, pero `GET /rules` exige
> `scripts:read`. Si tu integración lista reglas, incluye `scripts:read` en el token.

> **Lecturas que generan datos**
>
> `GET /reports/pci` sin `period_start` y `period_end` genera un reporte nuevo en cada llamada, incluso con un token de
> solo lectura. Consulta [Recetas](https://docs.proteside.com/es/docs/api/recipes#descargar-el-reporte-pci-dss-en-pdf) para descargar reportes sin
> generar copias.

## Revocar un token
En **Ajustes → API**, haz clic en **Revocar** en la fila del token y confirma. El efecto es inmediato: la siguiente
llamada con ese token recibe `401 Invalid token`. El token sigue en la lista con el estado **Revocado**, como
historial.

No existe ningún endpoint en la API para crear, listar o revocar tokens: esto solo se hace desde el dashboard.

## Buenas prácticas
* **Un token por integración.** Así puedes revocar uno sin tumbar los demás, y la auditoría muestra qué sistema hizo
  cada cambio.
* **Menor privilegio.** Un recolector de alertas para el SIEM solo necesita `alerts:read`. Un pipeline que solo
  descarga reportes solo necesita `reports:read`.
* **Guárdalo en una bóveda de secretos** (AWS Secrets Manager, GCP Secret Manager, Vault, variables protegidas del CI).
  Nunca pongas el token en el código fuente, en el front-end ni en los logs.
* **Rota con superposición.** Crea el token nuevo, actualiza la integración, confirma en la columna **Último uso** que
  el anterior dejó de usarse y solo entonces revoca el anterior. Prefiere una vigencia de 90 o 365 días para forzar la
  rotación.
* **Revócalo ante la menor señal de filtración.** El token da acceso a todas las tiendas de la organización.

## Próximos pasos
- [Convenciones](https://docs.proteside.com/es/docs/api/conventions): Paginación, errores, límite de solicitudes e idempotencia.
- [Tokens en el dashboard](https://docs.proteside.com/es/docs/guide/settings/api-tokens): La pantalla Ajustes → API en detalle.
