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"
    }
  ]
}