Authentication¶

Estia API runs on Keycloak (OAuth 2.0 / OIDC). Your backend gets a JWT via the client_credentials flow and sends it on every call.

Flow overview¶

sequenceDiagram
    participant App as Your backend
    participant KC as Keycloak
    participant API as Estia API

    App->>KC: POST /token<br/>grant_type=client_credentials<br/>client_id + client_secret
    KC-->>App: access_token, expires_in
    App->>API: Request with Authorization: Bearer <token>
    API->>API: Validate signature, issuer, audience, expiry
    API-->>App: Response payload

Why `client_credentials`¶

Machine-to-machine integration. No end-user login, so client_credentials is the right flow for server-side calls, scheduled jobs, and internal services.

Get a token¶

curl -X POST "https://auth.insurancegateway.gr/realms/estia/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<your-client-id>" \
  -d "client_secret=<your-client-secret>"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "expires_in": 300,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0,
  "scope": "openid profile"
}

Token lifetime¶

Usually 5 minutes to 1 hour — depends on the environment.

In client_credentials flow there's no refresh_token. When it's near expiry, request a new one.

In practice:

cache the token in your service layer
refresh a few minutes before expiry
don't refresh on every request

This keeps Keycloak traffic low and avoids edge cases with tokens expiring mid-flight.

JWT claims worth knowing¶

Claim	What it is
`sub`	Service-account user ID
`azp`	Your `client_id` — useful for auditing/per-client limits
`iss`	`https://auth.insurancegateway.gr/realms/estia`
`aud`	`estia-api`
`exp`	Expiry
`iat`	Issued at
`scope`	Granted scopes

What the API checks¶

JWT signature
Issuer
Audience
Expiry
not before, when present

Any failure → 401 Unauthorized.

Common auth failures¶

HTTP	What it means	What to check
`401 Unauthorized`	Token missing, expired, or invalid	Fresh token, correct header
`401 invalid_token`	Signature/issuer/audience mismatch	Realm config, token source
`403 Forbidden`	Token OK but missing permission	Contact us about roles/scopes

Implementation tip¶

Most common mistake: a new token on every call. Build token caching from day one.

Working examples in Code samples.

Docs use a different login

Browser login for Scalar is separate — only for browsing the spec. Your integration keeps using the service-account credentials.