Toda operación madura acaba topándose con la misma petición: “integre el portal con nuestro sistema”. Ya sea un script de importación, un panel externo o un conector de monitoreo, las integraciones necesitan credenciales propias — no la contraseña de un empleado. Para eso existen las API Keys del Portal Nyverra ITSM.

Esta guía explica qué son, cómo funcionan los alcances, cómo usarlas en la API REST y por qué el Portal del Desarrollador es el punto de partida del integrador.

Interfaz del módulo en el Portal Nyverra ITSM.

¿Qué es una API Key?

Es una credencial que autentica llamadas máquina a máquina (M2M) a la API del Portal, sin sesión de usuario. En lugar de “iniciar sesión como alguien”, el sistema integrador presenta la clave y recibe acceso según los alcances concedidos.

Esto trae tres ventajas inmediatas: segregación (la integración no es una persona), control (la clave tiene alcance limitado) y trazabilidad (las acciones quedan asociadas a la clave).

Alcances: qué puede hacer la clave

Una buena API Key no tiene acceso total — tiene lo necesario. En el Portal Nyverra, las operaciones están protegidas por alcances, por ejemplo:

Alcance	Permite
posts:read / posts:write	Leer y crear/actualizar contenido
taxonomy:read / taxonomy:write	Leer y crear categorías/etiquetas
media:write	Enviar archivos/multimedia
ai:generate	Usar funciones de generación de contenido
posts:delete / posts:purge	Eliminar (con y sin recuperación)

Aplicar el menor alcance es lo que reduce el daño en caso de que la clave se filtre.

Cómo usar en la API REST

La API acepta la clave en el encabezado, generalmente como Authorization: Bearer <clave> o X-API-Key: <clave>. El Portal del Desarrollador (documentación de la API) reúne los endpoints, parámetros y ejemplos — y, en el caso del blog, hay una referencia interactiva dedicada.

Quién usa

Perfil	Uso
Desarrollador / integrador	Consume la API con la clave
Administrador	Crea, asigna alcances, desactiva y rota claves

Cómo usar: paso a paso

1. Cree una clave por integración (nunca una sola para todo).
2. Aplique el menor alcance necesario.
3. Guarde en una bóveda de secretos — jamás en el código o en Git.
4. Use la clave en el encabezado de las llamadas.
5. Monitoree el uso y rote periódicamente.
6. Revoque la clave al desactivar la integración.

Reglas de negocio y seguridad

Regla	Explicación
Una clave por sistema	Facilita revocar sin afectar otras integraciones.
Alcance mínimo	Limita el impacto de una filtración.
Rotación	Reduzca la ventana de exposición; cambie las claves periódicamente.
Nunca versionar	Las claves en el repositorio son una filtración esperando a ocurrir.
Auditoría	El uso de la clave debe ser registrado y monitoreado.

Buenas prácticas

• Trate la API Key como credencial sensible: bóveda, no código.
• Rote con regularidad y revoque claves inactivas.
• Use alcances para separar lectura de escritura y limitar eliminaciones.
• Prefiera claves distintas por entorno (homologación ≠ producción).
• Documente qué integración usa qué clave.

Errores comunes

Situación	Qué hacer
“La clave puede todo”	Reasigne alcances: aplique el menor privilegio.
Clave en el repositorio	Revoque inmediatamente y muévala a la bóveda.
Clave antigua olvidada	Revise y revoque claves sin uso.
Error API_KEY_SCOPE_DENIED	Falta alcance para la operación; ajuste la clave.

Preguntas frecuentes

¿La API Key sustituye el inicio de sesión de usuario?
Para integraciones M2M, sí; para uso humano, no.

¿Puedo usar la misma clave en dos sistemas?
Técnicamente sí, pero es una mala práctica — dificulta revocar y auditar.

¿Dónde veo los endpoints?
En el Portal del Desarrollador / documentación de la API REST.

Escenarios de uso: integraciones reales

1. Sincronización con sistema externo. Un script nocturno importa datos de otro sistema usando una clave con alcance solo de lectura — reduciendo lo que una filtración podría exponer.

2. Conector de monitoreo. Zabbix crea tickets vía API con una clave dedicada de escritura, separada de cualquier credencial humana.

3. Automatización con agente. Herramientas de IA o informes usan ai:generate y alcances específicos, sin acceso a eliminaciones.

KPIs y gobernanza de claves

Indicador	Qué revela
Claves activas por integración	Inventario de accesos M2M
Edad de la última rotación	Postura de seguridad
Claves con alcance amplio	Riesgo de privilegio excesivo
Claves sin uso reciente	Candidatas a revocación

Respuesta a incidente de clave expuesta

Si una clave se filtra, el tiempo importa. El procedimiento: revocar inmediatamente, crear una nueva con alcance mínimo, actualizar la integración e investigar el uso indebido mediante la auditoría. Use alcances separados para que la rotación de una integración no afecte a las demás — y nunca versione claves. Tratar la API Key como credencial de primera clase es lo que permite a la empresa abrir la API sin abrir un flanco de seguridad.

Checklist de API Keys

1. Una clave por integración.
2. Aplique el menor alcance.
3. Guarde en bóveda de secretos.
4. Rote periódicamente.
5. Monitoree el uso.
6. Revoque claves inactivas.

Preguntas frecuentes adicionales

¿Dónde usar la clave?
En el encabezado Authorization o X-API-Key de las llamadas.

¿Puedo usar la misma clave en pruebas y producción?
Mejor no; separe por entorno.

¿Qué hacer si se filtra?
Revocar inmediatamente, crear una nueva e investigar mediante la auditoría.

Conclusión

Con API Keys bien gestionadas, el Portal Nyverra ITSM se integra con seguridad y sin depender de credenciales humanas. Alcances mínimos, rotación y auditoría transforman “abrir la API” en una integración controlada y sostenible.