Claves de API
Las API keys autentican el acceso de máquinas (scripts, jobs de cron y el servidor MCP integrado) a la API REST de Chinaski. El acceso vive bajo Settings → API Keys (/admin/api-keys), solo para admin. Esta página cubre cómo crearlas, darles ámbito y revocarlas; el modelo de peticiones (scopes, límites de tasa) está en su propia página de Automation.
Crear una key
- Haz clic en crear; dale a la key un nombre (obligatorio; los nombres son los identificadores de auditoría para siempre) y un permiso:
- read: puede obtener contenido pero nunca modificarlo.
- write: puede crear y actualizar; requerido para cada llamada de mutación.
- Opcionalmente establece una fecha de expiración (una fecha simple; dejarla vacía significa que la key nunca expira).
- La key en sí es una cadena larga aleatoria generada por una fuente aleatoria segura, se muestra exactamente una vez en un campo de copia justo después de crearla, con una nota explícita de que no se mostrará de nuevo. Solo se almacena un hash de ella (y para las keys recién creadas, una capa de verificación bcrypt encima), así que una base de datos filtrada no puede revelar keys vivas.
- Las creaciones se auditan (la acción nombra la key y su scope).
Ámbitos en la práctica
- Los cards hacen flux-group de lectura/escritura por diseño: el scope read no puede crear ni editar nada.
- El scope write es requerido por cada endpoint que manipula contenido, tanto en rutas "seguras" como administrativas, así una key acuñada como reportero de solo lectura no puede colarse por la puerta golpeando una ruta menos conocida.
- Una puerta de aserción amplia frente a las rutas autenticadas por sesión ahora revisa el scope por método, así que las llamadas de escritura con keys de lectura obtienen un 403 limpio en lugar de un silencioso derrame de permisos.
Límite de tasa
El límite de tasa es por key, por ventana móvil de 60 segundos, con un valor por defecto de 100 peticiones por minuto (configurable en Settings → Security: "API key rate limit"). Cruzar el límite devuelve una respuesta 429 con un header Retry-After que indica al script cuánto esperar. Cada petición incrementa el contador exactamente una vez, sin importar cuántas capas internas de autenticación atraviese.
Feedback de uso de keys: cada key registra la última vez que se autenticó; el uso reciente es visible en la pantalla de keys, y cada petición se audita (método y path), que es la forma más rápida de encontrar keys abandonadas.
El kill switch
El toggle maestro "API access" en la misma pantalla desactiva todas las peticiones de API, en un solo interruptor. Con el acceso apagado, la API responde a cada petición con un 503, ignorando las keys, útil durante incidentes sin cazar tu lista de keys. La acción del toggle en sí se audita con el estado resultante.
Revocación
Borrar una key es instantáneo y auditado: la key deja de funcionar inmediatamente después. El hábito de limpieza más seguro: el audit trail encuentra fechas de último uso por key; una key con un timestamp de último uso rancio y un origen de prueba hace una política de retiro ordenada.