Autenticación y claves API

La API Scan de Cert-IX utiliza claves API para el acceso programático. Las claves API ofrecen alcances granulares, restricciones por tipo de análisis, límites de tasa por clave, lista de IPs permitidas, expiración automática y rotación sin interrupciones.

Métodos de autenticación

Método	Caso de uso	Encabezado
Clave API	Acceso programático (scripts, CI/CD, integraciones)	X-API-Key
JWT	Operaciones del panel de control (gestión de claves API)	Authorization: Bearer <token>

Esta página cubre la autenticación por clave API. La autenticación JWT es gestionada automáticamente por el panel de control de Cert-IX.

Formato de las claves API

Las claves API de Cert-IX siguen un formato determinístico para una identificación fácil:

cix_sk_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Segmento	Descripción
cix_	Prefijo de la plataforma Cert-IX
sk_	Identificador de tipo clave secreta
XXX...	Cadena criptográfica aleatoria de 40 caracteres

Seguridad

Las claves API se hashean con SHA-256 antes del almacenamiento. La clave en texto plano se muestra solo una vez al crearla. Cert-IX no puede recuperar su clave si se pierde — debe realizar una rotación.

Transmitir su clave API

Incluya su clave API en el encabezado X-API-Key en cada solicitud:

curl -X GET https://api.cert-ix.com/scan-api/api/v1/scans \
  -H "X-API-Key: cix_sk_su_clave_api_aqui"

Nunca transmita claves API en parámetros de URL

Las cadenas de consulta pueden registrarse en logs de acceso del servidor, historial del navegador y cachés de proxy.

Crear una clave API

Endpoint

POST /api/v1/api-keys

Cuerpo de la solicitud

{
  "name": "Pipeline CI/CD - Producción",
  "description": "Utilizada por GitHub Actions para análisis de vulnerabilidades nocturnos",
  "scopes": [
    "scans:create",
    "scans:read",
    "scans:list",
    "results:read",
    "webhooks:read"
  ],
  "allowedScanTypes": ["nmap", "nuclei", "trivy", "zap"],
  "allowedIpAddresses": ["203.0.113.50", "198.51.100.0/24"],
  "rateLimitPerMinute": 30,
  "rateLimitPerHour": 500,
  "rateLimitPerDay": 5000,
  "expiresInDays": 90
}

Parámetros de la solicitud

Campo	Tipo	Requerido	Descripción
name	string	Sí	Nombre legible de la clave (máx. 255 caracteres)
description	string	No	Descripción de uso opcional
scopes	string[]	No	Alcances de permisos (predeterminado: todos los alcances)
allowedScanTypes	string[]	No	Motores de análisis permitidos (predeterminado: todos)
allowedIpAddresses	string[]	No	Rangos IP/CIDR de origen permitidos
rateLimitPerMinute	integer	No	Solicitudes máx. por minuto
rateLimitPerHour	integer	No	Solicitudes máx. por hora
rateLimitPerDay	integer	No	Solicitudes máx. por día
expiresInDays	integer	No	Expiración en días (0 o null = sin expiración)

Respuesta (201 Created)

{
  "success": true,
  "data": {
    "apiKey": {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Pipeline CI/CD - Producción",
      "keyPrefix": "cix_sk_001e3c",
      "scopes": ["scans:create", "scans:read", "scans:list", "results:read", "webhooks:read"],
      "allowedScanTypes": ["nmap", "nuclei", "trivy", "zap"],
      "status": "active",
      "expiresAt": "2026-06-04T10:00:00Z",
      "createdAt": "2026-03-06T10:00:00Z"
    },
    "rawKey": "cix_sk_001e3c2d92ffb23344a943df2b6a001fb1028d002"
  }
}

Crítico

El campo rawKey se devuelve solo al momento de la creación. Cópielo inmediatamente y almacénelo en una bóveda segura (ej.: HashiCorp Vault, AWS Secrets Manager o el almacén de secretos de su CI/CD).

Alcances y permisos

Los alcances controlan las acciones que una clave API está autorizada a realizar. Aplique el principio de mínimo privilegio — otorgue solo los alcances necesarios para su integración.

Alcances disponibles

Alcance	Descripción
scans:create	Enviar nuevos análisis
scans:read	Ver detalles y estado de un análisis
scans:list	Listar todos los análisis del tenant
scans:cancel	Cancelar análisis en curso
results:read	Obtener resultados y hallazgos
templates:create	Crear plantillas de análisis
templates:read	Ver plantillas de análisis
templates:update	Modificar plantillas de análisis
templates:delete	Eliminar plantillas de análisis
webhooks:create	Registrar y probar webhooks
webhooks:read	Ver configuraciones y registros de entrega
webhooks:update	Modificar configuraciones de webhooks
webhooks:delete	Eliminar webhooks
usage:read	Ver analíticas de uso y cuotas

Conjuntos de alcances recomendados

Pipeline CI/CD (lectura-escritura de análisis):

["scans:create", "scans:read", "scans:list", "results:read"]

Panel de monitoreo (solo lectura):

["scans:read", "scans:list", "results:read", "usage:read"]

Automatización completa (análisis + webhooks + plantillas):

["scans:create", "scans:read", "scans:list", "scans:cancel", "results:read",
 "templates:create", "templates:read", "templates:update",
 "webhooks:create", "webhooks:read"]

Tipos de análisis permitidos

Restrinja los motores de análisis que una clave API puede invocar:

• Aísle las claves CI/CD solo a análisis de contenedores (ej.: trivy)
• Limite las claves OSINT a reconocimiento pasivo (ej.: harvester, sublist3r)
• Restrinja las claves web a escáneres web (ej.: zap, nikto, wapiti)

Tipos de análisis disponibles: nmap, zap, trivy, nuclei, nikto, sqlmap, wapiti, harvester, sublist3r, sentinel

Lista de IPs permitidas

Bloquee una clave API a direcciones IP de origen o rangos CIDR específicos. Las solicitudes desde otras IPs son rechazadas con 403 IP_NOT_ALLOWED.

Formatos soportados:

• IP única: "203.0.113.50"
• Rango CIDR: "198.51.100.0/24"
• IPv6: "2001:db8::1"

Límites de tasa

Ventana	Predeterminado	Rango configurable
Por minuto	60	1 – 1.000
Por hora	1.000	1 – 50.000
Por día	10.000	1 – 500.000

Encabezados de límite de tasa

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1709654460

Límite de tasa excedido

{
  "success": false,
  "error": "Límite de tasa excedido. Reintente en 23 segundos.",
  "code": "RATE_LIMIT_EXCEEDED"
}

Estado HTTP: 429 Too Many Requests

Rotación de claves

Realice la rotación de claves API con cero tiempo de inactividad gracias al mecanismo de período de gracia.

Endpoint

POST /api/v1/api-keys/:keyId/rotate

Flujo de trabajo de rotación

1. POST /api-keys/:claveAntiguaId/rotate  → Nueva clave creada, antigua en período de gracia
2. Actualice su almacén de secretos con la nueva clave
3. Despliegue la nueva clave en sus servicios
4. La clave antigua expira automáticamente después del período de gracia

Buena práctica

Realice la rotación de claves cada 90 días. Automatice la rotación en su infraestructura o establezca un recordatorio en el calendario.

Revocación de claves

Desactive inmediata y permanentemente una clave API. La revocación es instantánea — la clave deja de funcionar inmediatamente.

Endpoint

DELETE /api/v1/api-keys/:keyId

Estados de las claves

Estado	Descripción
active	La clave está plenamente operativa
revoked	La clave ha sido permanentemente desactivada
expired	La clave ha superado su fecha expiresAt
suspended	La clave ha sido temporalmente suspendida por un administrador

Mejores prácticas de seguridad

Lo que debe hacer

• ✅ Almacene las claves en un gestor de secretos (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault)
• ✅ Use variables de entorno — nunca codifique las claves directamente
• ✅ Aplique mínimo privilegio — otorgue solo los alcances necesarios
• ✅ Establezca fechas de expiración — rotación cada 90 días
• ✅ Use lista de IPs permitidas para infraestructura estática
• ✅ Monitoree el uso vía los endpoints de analíticas de uso
• ✅ Revoque inmediatamente si una clave está comprometida

Lo que no debe hacer

• ❌ Nunca haga commit de claves en el control de versiones (Git, SVN)
• ❌ Nunca transmita claves en parámetros de URL
• ❌ Nunca comparta claves entre equipos o entornos
• ❌ Nunca registre claves API en logs de la aplicación

---

Próximos pasos:

• Envío de análisis →
• Plantillas de análisis →
• Referencia de errores →