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

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	Value
`X-API-Key`	Your API Key (obtained from the dashboard)
`Content-Type`	`application/json`

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)

{
  "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

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

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

# 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

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