Skip to content
GERION
ES EN

M2M Authentication

The Gerion public API uses machine-to-machine (M2M) authentication for the CLI and CI/CD pipelines. The flow is: long-lived API Key → short-lived JWT.

Authentication flow

Section titled “Authentication flow”
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

Section titled “Endpoint”
POST https://api.gerion.dev/api/v1/auth/m2m/authenticate

Headers

Section titled “Headers”

| Header | Value | |--------|-------| | X-API-Key | Your API Key (obtained from the dashboard) | | Content-Type | application/json |

Body

Section titled “Body”
{
  "client_id": "my-jenkins-runner"
}

| Field | Type | Description | |-------|------|-------------| | client_id | string | Client identifier. 3–50 alphanumeric characters, ., -, _. Must match the client_id registered with the API Key. |

Success response (200)

Section titled “Success response (200)”
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 1800,
  "client_id": "my-jenkins-runner",
  "api_key_id": "key-abc123"
}

| Field | Description | |-------|-------------| | access_token | RS256-signed JWT. Include in Authorization: Bearer for subsequent calls. | | expires_in | Validity in seconds (1800 = 30 minutes). |

Common errors

Section titled “Common errors”

| Code | Cause | |------|-------| | 401 | Invalid or revoked API Key, or client_id mismatch. | | 404 | API Key not found. | | 429 | Rate limit exceeded (30 req/s, burst 10). |

Using the JWT

Section titled “Using the JWT”

Once you have the token, include it in all subsequent calls:

Ventana de terminal
# 1. Authenticate and obtain 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": "my-runner"}' \
  | jq -r '.access_token')


# 2. Use the JWT to upload findings
curl -X POST https://api.gerion.dev/api/v1/findings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @findings.json

JWKS — RS256 public key

Section titled “JWKS — RS256 public key”

If you need to validate tokens externally (e.g. from another service that verifies Gerion JWTs):

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

Returns the public key set in standard JWKS format (RFC 7517). No authentication required.

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