Proteside Tokens y alcances
Crea tokens de la API en Ajustes → API, elige los alcances correctos y envía el token en el header Authorization.
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.
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:
curl -s "https://app.proteside.com/api/v1/stores" \
-H "Authorization: Bearer ps_live_Ab3dEf6hIj9kLm2nOp5qRs8t_..."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_Ab3dEf6hIj9kLm2nOp5qRs8t).
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) |
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 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 necesitareports: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.