Claves de API

Una clave de API autoriza a un sistema externo, por ejemplo tu ERP, a usar la REST API v1 de exoCortex: abrir tickets, leer su estado y agregar comentarios. Cada clave pertenece a un tenant y solo ve los tickets de ese tenant.

Crear una clave

1. En exoCortex Core abre Integrations → API keys. Necesitas un rol administrativo, por ejemplo it_admin o integration_admin.
2. Dale a la clave un nombre que diga quién la usa, por ejemplo «Conector ERP».
3. Elige los scopes, es decir, lo que la clave puede hacer (consulta abajo).
4. Copia la clave completa y guárdala en el gestor de secretos del sistema que la va a usar. exoCortex la muestra una sola vez y solo guarda una huella: si la pierdes, creas una clave nueva.

La clave tiene la forma nhk.<keyid>.<secret>. El keyid identifica la clave en la lista; el secret solo lo tienes tú.

Scopes

Scope	Qué permite
tickets:create	Abrir tickets
tickets:read	Leer el estado de un ticket
tickets:comment	Agregar comentarios a un ticket
tickets:*	Todas las operaciones sobre tickets
*	Todo lo que permite la API v1

Asigna a cada clave solo los scopes que necesita. Una clave sin scopes tiene acceso completo a la API v1: está permitido, pero no se recomienda.

Usar la clave

Envía la clave en el encabezado Authorization de cada solicitud:

POST /api/v1/tickets HTTP/1.1
Host: exocortex-api.ai-exo-cortex.com
Authorization: Bearer nhk.9f2c4e1a7b3d.…
Content-Type: application/json
Idempotency-Key: 6b1f0c4e-2a7d-4b39-9e51-8c3d2f7a1b60

{ "subject": "Payment gateway returns HTTP 502", "priority": "High" }

También puedes usar el encabezado X-NH-API-Key. El tenant no se indica: exoCortex lo obtiene de la clave.

Usa siempre Idempotency-Key cuando abras un ticket: si repites la solicitud con la misma clave de idempotencia, recibes el ticket que ya se creó en lugar de un duplicado.

Límites de frecuencia

Cada clave tiene un límite de solicitudes: el valor predeterminado es de 600 solicitudes cada 60 segundos. Cada respuesta te indica en qué punto estás:

Encabezado	Significado
RateLimit-Limit	Solicitudes permitidas en la ventana
RateLimit-Remaining	Solicitudes que aún tienes disponibles
RateLimit-Reset	Segundos para la nueva ventana
Retry-After	Solo con la respuesta 429: segundos que debes esperar antes de reintentar

Errores

Los errores de la API v1 devuelven un JSON con ok: false, un mensaje legible en error y un código estable en code. Basa la lógica de tu cliente en el code, no en el mensaje.

code	Estado HTTP	Qué hacer
missing_api_key	401	Agrega el encabezado Authorization
invalid_api_key	401	Revisa la clave: puede ser incorrecta o estar revocada
insufficient_scope	403	Agrega a la clave el scope indicado en required_scope
api_key_disabled	403	La clave está desactivada: usa una clave activa
validation_error	400	Corrige el campo indicado en field
not_found	404	El ticket no existe o no pertenece al tenant de la clave
rate_limited	429	Espera los segundos indicados en Retry-After
ingest_failed	500	Reintenta con la misma Idempotency-Key

exoCortex puede agregar códigos nuevos: si recibes uno que no conoces, decide según el estado HTTP.

Revocar una clave

Desde Integrations → API keys revocas una clave cuando un sistema ya no la usa o si crees que quedó expuesta. La revocación es inmediata. La lista también muestra el último uso de cada clave: te ayuda a encontrar las claves inactivas.

Claves nh_… obsoletas

Las claves con el formato anterior nh_… funcionan hasta el 30 de junio de 2027. Las respuestas a estas claves incluyen los encabezados Deprecation y Sunset. Para migrar, crea una clave nhk. con los scopes necesarios, actualiza el sistema que la usa y luego revoca la clave anterior.