# Seguridad

> Lista de comprobación para integrar la API, los webhooks y la publicación en tu propia API de Blogenia con el menor riesgo posible.

Versión web: https://blogelia.com/docs/seguridad

Una integración segura son pocas costumbres bien aplicadas. Repasa esta lista antes de salir a producción.

## Claves de API

- **Permisos mínimos.** Marca solo los [permisos](https://blogelia.com/docs/autenticacion#scopes) que la integración necesita. Una web que muestra artículos necesita `content:read`; un dashboard de visitas, solo `stats:read`.
- **Dashboard de analítica: una clave solo con `stats:read`.** No lee artículos ni datos de la cuenta. Si además necesitas créditos o estados de artículos, usa una segunda clave aparte con `account:read`.
- **Nunca `account:read` en el navegador ni en código de front-end.** Da acceso a datos internos de la cuenta (créditos, generaciones, piloto, entregas). Úsala solo en tu servidor; esas rutas no admiten CORS a propósito.
- **Los permisos no se amplían.** Si una clave se queda corta, crea otra con los permisos nuevos y revoca la antigua: así una clave filtrada nunca gana acceso. Ver [Rotar una clave](#rotar).
- **Solo en el servidor.** Nunca en el navegador, en una app móvil ni en código que se descargue: cualquiera podría leerla. Pide los datos desde tu servidor y entrega el resultado al visitante.
- **Variables de entorno o gestor de secretos**, nunca en el repositorio. Si una clave llegó a git, trátala como filtrada.
- **Una clave por integración o entorno** (producción, pruebas, cada servicio). El panel te deja tener hasta 10 claves activas y ponerles nombre.
- **Revoca las que no uses.** En **API**, la lista muestra el último uso de cada clave; revoca las que llevan tiempo sin usarse.
- **Mira las cabeceras `X-RateLimit-*`** para detectar un uso anormal. Ver [Límites de uso](https://blogelia.com/docs/limites).

### Rotar una clave

Las claves no caducan solas, así que rótalas tú. Recomendamos hacerlo cada 90 días y de inmediato si sospechas que se ha filtrado.

1. En el [panel](https://app.blogelia.com/api), crea una clave nueva.
2. Despliega tu servidor con la clave nueva.
3. Comprueba que funciona y que la antigua ya no aparece como usada.
4. **Revoca** la antigua. Deja de funcionar al instante en el proceso que la revoca y, como máximo, 30 segundos después en el resto.

## Webhooks

- **Solo `https`.** El panel no admite otra cosa en producción.
- **Verifica la firma** de cada petición con una comparación en tiempo constante (`timingSafeEqual`, `compare_digest`, `hash_equals`). Ver el código en [Webhooks](https://blogelia.com/docs/webhooks#firma).
- **Rechaza timestamps antiguos.** La firma cubre `Blogenia-Timestamp`: descarta lo que tenga más de 5 minutos.
- **Sé idempotente.** Guarda el valor de `Blogenia-Delivery` y no proceses dos veces el mismo.
- **Responde `2xx` rápido** y procesa en segundo plano: tienes 10 segundos.
- **No uses el cuerpo para autorizar nada.** Úsalo como aviso y, si necesitas datos fiables, pide el artículo a la [API](https://blogelia.com/docs/articulos) con tu clave.
- **Trata el secreto como una contraseña**: variable de entorno, nunca en git ni en logs.

### Rotar el secreto de un webhook

El panel muestra el secreto una sola vez y no lo regenera. Para cambiarlo:

1. Añade un webhook nuevo con la misma URL (o una nueva) y copia su secreto.
2. Haz que tu servidor acepte las dos firmas durante un tiempo, o despliega con el secreto nuevo.
3. Elimina el webhook antiguo desde **API** en el panel.

## Receptor de “Publicar en tu propia API”

- **Acepta solo peticiones con tu credencial.** Blogenia envía la clave de acceso que configuraste como `Authorization: Bearer <clave>` y la guarda cifrada (AES-256-GCM). Rechaza con `401` cualquier otra petición, y compara la clave en tiempo constante.
- **Usa `Idempotency-Key` y `sourceId`** para no duplicar artículos ante reintentos.
- **Sanea o limita el HTML** también en tu lado (lista blanca de etiquetas y atributos) antes de mostrarlo.
- **Limita las peticiones** con un rate limit en esas rutas.
- **Expón solo las rutas necesarias**: comprobar, crear, consultar, actualizar y borrar bajo la ruta que configuraste.
- **Una credencial distinta por entorno** (producción y pruebas).
- **Solo `https`** y un certificado válido: Blogenia no se conecta a otras direcciones.

### Cambiar la credencial

En **Blog**, pestaña **Publicación**, escribe la clave nueva en **Clave de acceso** y guarda. Antes, haz que tu API acepte la nueva. Vuelve a comprobar la conexión.

> **Nota:** Si ves algo raro o sospechas una filtración, revoca la clave o elimina el webhook primero y analiza después.