Llaves y autenticación

Cómo crear, guardar, rotar y revocar llaves `sk_live_`, la diferencia entre lectura y escritura, y las cabeceras con las que se autentica cada llamada.

Una llave de API es la credencial de un sistema, no de una persona. No pertenece a quien la creó: sigue funcionando si esa persona se va de la empresa y no gana permisos si la ascienden. Todo lo que escribe queda registrado a nombre de la llave (api_key:<id>), no de su creador.

Crear una llave en la app

1. Abre Automatización y entra a la pestaña «API Keys». Necesitas ser analista o administrador.
2. Pulsa «Generar key». Aparece un formulario en línea.
3. En «Nombre de la key (ej. 'Integración ERP')» escribe el nombre del sistema que la usará. Es lo que verás en la lista y en el registro de consumo.
4. Elige el permiso: «Solo leer» o «Leer y escribir». Viene en «Solo leer»: si tu integración sube archivos o registra órdenes, cámbialo a propósito.
5. Pulsa «Crear». Arriba aparece «Key generada — cópiala ahora. No se volverá a mostrar.» con la llave completa y el botón «Copiar».
6. Pulsa «Copiar», pégala en el gestor de secretos de tu sistema y cierra el aviso con la ✕.

La lista de llaves

Nombre

El nombre que le diste al crearla.

Permiso

«Lectura» o «Lectura y escritura».

Creada

La fecha de creación.

Último uso

El día de la última llamada que hizo, o «Nunca». Se actualiza como mucho una vez por minuto: sirve para saber si una llave sigue en uso antes de revocarla.

Revocar

Borra la llave. Pide confirmación: «¿Revocar esta API key? Las apps que la usen dejarán de funcionar.»

Si todavía no hay ninguna, la pestaña dice «Aún no tienes API keys.». Debajo de la lista está la tarjeta «Sandbox para desarrolladores»: ver Sandbox y versiones.

Lectura o escritura

Ninguna llave puede ser administrador. Una llave de lectura que intenta escribir recibe 403 con error_code: "api_key_scope_insufficient" y error_params: {"required_scope": "write", "key_scope": "read"}. Usa la llave más débil que alcance: una de lectura para un tablero de BI o un asistente, una de escritura solo para el proceso que de verdad escribe.

Cómo se manda la llave

Va en la cabecera Authorization con el prefijo Bearer. Para herramientas de BI que no permiten esa cabecera, también se acepta X-API-Key. Si mandas las dos, gana Authorization. Nunca pongas la llave en la URL: los proxies y el historial del navegador guardan las URLs.

# The usual way
curl https://app.stockai.es/api/v1/planning -H "Authorization: Bearer sk_live_..."

# For tools that cannot set Authorization (Power BI web connector, Excel Power Query, Looker)
curl https://app.stockai.es/api/v1/planning -H "X-API-Key: sk_live_..."

Lo que una llave nunca alcanza

Con una llave se llega a casi todo lo que hace la app. Hay rutas que son de una persona y no de un sistema, y responden 403 api_key_route_not_exposed (en error_params.reason viene el motivo):

• Iniciar sesión, usuarios, roles y la gestión de las propias llaves (una llave no puede crear, listar ni revocar llaves).
• Preferencias personales, mensajes del equipo y conversaciones con el asistente.
• Exportar o borrar la cuenta, la configuración de la instalación y el proveedor de IA.
• Decisiones que llevan el nombre de una persona: aprobar órdenes, cancelarlas o marcarlas pagadas, pedidos comprometidos de clientes, contratos, presupuestos, ajustes de pronóstico y consenso.
• Configurar la entrega de archivos (SFTP/S3) y crear un sandbox: lo hace un administrador en la pantalla.

HTTP/1.1 403 Forbidden
{"detail":"This endpoint cannot be called with an API key.",
 "error_code":"api_key_route_not_exposed",
 "error_params":{"reason":"internal tag 'users': user and password management belongs to people, not to a credential"}}

Rotar una llave sin cortar el servicio

1. Crea una llave nueva con el mismo permiso y un nombre que la distinga (por ejemplo «ERP nocturno 2026-10»).
2. Cámbiala en el gestor de secretos de tu sistema y despliega.
3. Espera a que «Último uso» de la llave vieja deje de moverse y la nueva muestre la fecha de hoy.
4. Revoca la vieja con «Revocar».

Ten en cuenta el tope de llaves de tu plan (3 en Pro, 10 en Max): para rotar necesitas un lugar libre durante unos minutos.

Revocar

Revocar es inmediato e irreversible: la siguiente llamada con esa llave recibe 401 api_key_invalid, igual que una llave que nunca existió (a propósito: no se revela si existió). Las llamadas que hizo antes siguen contando en el consumo del mes.

HTTP/1.1 401 Unauthorized
{"detail":"API key is invalid or expired","error_code":"api_key_invalid","error_params":{}}

Qué queda registrado

• Cada escritura de una llave queda en el registro de la cuenta con el nombre de la llave, la ruta y el resultado.
• Lo que se rechaza en la puerta (401, 403 de alcance o permiso, 429) no deja registro ni cuenta como consumo: si escribes con una llave de lectura, lo verás en tu lado, no en el registro.
• Cada llave nueva genera el evento «se creó una API key», visible para los administradores.