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.

Note

This endpoint is the only authentication mechanism exposed publicly. User login flows (password, MFA, SSO) are reserved for the frontend and are not directly accessible from the internet.

Authentication flow

sequenceDiagram
    accTitle: M2M authentication flow
    accDescr: The CLI sends its API Key, receives a JWT valid for 30 minutes and uses it to upload the findings.
    autonumber
    participant CLI as CLI / CI/CD
    participant API as Gerion API
    CLI->>API: POST /api/v1/auth/m2m/authenticate<br/>X-API-Key header
    API-->>CLI: JWT (30 min)
    CLI->>API: POST /api/v1/findings<br/>Authorization: Bearer #lt;jwt#gt;
    API-->>CLI: 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"
    }
  ]
}