Seguridad de API
HTTPS
Toda la comunicación entre los clientes y los servicios de Percus se realiza sobre HTTPS. No se aceptan conexiones HTTP. La terminación TLS se gestiona en las capas de CloudFront y balanceador de carga antes de que el tráfico llegue a los servicios de aplicación.
Autenticación de la API del Backoffice
La API del Backoffice usa autenticación Bearer token. El token de sesión JWT emitido por NextAuth.js se reenvía con cada solicitud. El backend valida el token y extrae los roles del usuario antes de procesar cualquier operación.
Las solicitudes con tokens ausentes o inválidos reciben 401 Unauthorized. Las solicitudes con tokens válidos pero rol insuficiente reciben 403 Forbidden.
Credenciales de API (acceso programático)
Los proyectos que integran el Percus Player de forma programática utilizan credenciales de API — un par clave/secreto con alcance a un único proyecto.
| Propiedad | Detalle |
|---|---|
| Alcance | Por proyecto — una credencial no puede acceder a los recursos de otro proyecto |
| Formato de clave | Prefijo pk_... (clave pública, segura para incluir en configuraciones cliente) |
| Formato de secreto | Prefijo sk_... — devuelto una sola vez en la creación, almacenado como hash unidireccional |
| Rotación | POST /api/credentials/{id}/revoke — revocar y crear una nueva credencial |
| Quién puede gestionar | ProjectManager u OrganizationAdmin |
El secreto se muestra exactamente una vez. Si se pierde, crear una nueva credencial y revocar la anterior.
Seguridad postMessage del player
El Percus Player corre dentro de un <iframe> cross-origin y se comunica con la página host mediante la API postMessage. Se aplican los siguientes controles:
| Control | Cómo funciona |
|---|---|
| Lista blanca de orígenes | El player acepta comandos solo de orígenes en una lista blanca configurable. Los comandos de orígenes no listados se descartan silenciosamente. |
| Validación de origen | El SmartEmbed SDK valida que los mensajes entrantes provengan del iframe inyectado (event.source === iframe.contentWindow). Los mensajes de otras fuentes son ignorados. |
| Origen destino | En producción, las llamadas a postMessage deben apuntar al dominio conocido del player en lugar de usar "*". |
La página host es responsable de establecer los atributos sandbox apropiados en el elemento iframe.
Claves de idempotencia
Los endpoints de subida de templates aceptan una cabecera opcional Idempotency-Key. Si un fallo de red provoca que una subida se reintente, proporcionar la misma clave evita la creación de templates duplicados.
Rate limiting
El rate limiting se aplica en las capas de CloudFront y API Gateway. Los límites se configuran por entorno y por superficie de API. Los umbrales específicos se comunican durante el proceso de incorporación del cliente.