Autenticación M2M

La API pública de Gerion usa autenticación máquina a máquina (M2M) para la CLI y pipelines de CI/CD. El flujo es: API Key de larga duración → JWT de corta duración.

Flujo de autenticación

CLI / CI/CD
    │
    ├─ 1. X-API-Key header  ──►  POST /api/v1/auth/m2m/authenticate
    │                                       │
    │◄─ 2. JWT (30 min) ─────────────────────┘
    │
    ├─ 3. Authorization: Bearer <jwt>  ──►  POST /api/v1/findings
    │                                                │
    │◄─ 4. 201 Created ──────────────────────────────┘

Endpoint

POST https://api.gerion.dev/api/v1/auth/m2m/authenticate

Headers

| Header | Valor | |--------|-------| | X-API-Key | Tu API Key (obtenida desde el dashboard) | | Content-Type | application/json |

Body

{
  "client_id": "mi-runner-jenkins"
}

| Campo | Tipo | Descripción | |-------|------|-------------| | client_id | string | Identificador del cliente. 3–50 caracteres alfanuméricos, ., -, _. Debe coincidir con el client_id registrado en la API Key. |

Respuesta exitosa (200)

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 1800,
  "client_id": "mi-runner-jenkins",
  "api_key_id": "key-abc123"
}

| Campo | Descripción | |-------|-------------| | access_token | JWT firmado con RS256. Incluir en Authorization: Bearer para llamadas posteriores. | | expires_in | Validez en segundos (1800 = 30 minutos). |

Errores comunes

| Código | Causa | |--------|-------| | 401 | API Key inválida, revocada o client_id no coincide. | | 404 | API Key no encontrada. | | 429 | Rate limit superado (30 req/s, burst 10). |

Usar el JWT

Una vez obtenido el token, inclúyelo en todas las llamadas posteriores:

# 1. Autenticar y obtener JWT
TOKEN=$(curl -s -X POST https://api.gerion.dev/api/v1/auth/m2m/authenticate \
  -H "X-API-Key: $GERION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"client_id": "mi-runner"}' \
  | jq -r '.access_token')

# 2. Usar el JWT para subir findings
curl -X POST https://api.gerion.dev/api/v1/findings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @findings.json

JWKS — Clave pública RS256

Si necesitas validar tokens externamente (por ejemplo, desde otro servicio que verifique JWTs de Gerion):

GET https://api.gerion.dev/api/v1/auth/jwks

Devuelve el conjunto de claves públicas en formato JWKS estándar (RFC 7517). No requiere autenticación.

{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "gerion-api-gateway-key-1",
      "n": "...",
      "e": "AQAB"
    }
  ]
}