Authentication¶

Το Estia API τρέχει σε Keycloak (OAuth 2.0 / OIDC). Το backend σας παίρνει JWT μέσω client_credentials flow και το στέλνει σε κάθε 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 με Authorization: Bearer <token>
    API->>API: Validate signature, issuer, audience, expiry
    API-->>App: Response

Γιατί `client_credentials`¶

Machine-to-machine integration. Δεν υπάρχει end-user, οπότε client_credentials είναι το σωστό flow για server-side calls, scheduled jobs και internal services.

Πάρτε 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,
  "token_type": "Bearer",
  "scope": "openid profile"
}

Token lifetime¶

Συνήθως 5 λεπτά έως 1 ώρα — εξαρτάται από το environment.

Στο client_credentials flow δεν υπάρχει refresh_token. Όταν πλησιάζει η λήξη, ζητάτε νέο.

Πρακτικά:

cache το token στη service layer
refresh λίγα λεπτά πριν λήξει
μη κάνετε refresh σε κάθε request

Έτσι μειώνετε traffic στο Keycloak και αποφεύγετε edge cases με tokens που λήγουν mid-flight.

JWT claims που σας ενδιαφέρουν¶

Claim	Τι είναι
`sub`	Service-account user ID
`azp`	Το `client_id` σας — χρήσιμο για auditing/per-client limits
`iss`	`https://auth.insurancegateway.gr/realms/estia`
`aud`	`estia-api`
`exp`	Expiry
`iat`	Issued at
`scope`	Granted scopes

Τι ελέγχει το API¶

JWT signature
Issuer
Audience
Expiry
not before, αν υπάρχει

Σε αποτυχία → 401 Unauthorized.

Common auth failures¶

HTTP	Σημασία	Τι να ελέγξετε
`401 Unauthorized`	Token λείπει, έληξε ή invalid	Νέο token, σωστό header
`401 invalid_token`	Signature/issuer/audience mismatch	Realm config, token source
`403 Forbidden`	Token OK αλλά λείπει permission	Επικοινωνήστε για roles/scopes

Tip υλοποίησης¶

Το πιο συνηθισμένο λάθος: νέο token σε κάθε call. Βάλτε token caching από την αρχή.

Έτοιμα implementations σε Code samples.

Τα docs έχουν άλλο login

Το browser login για το Scalar είναι ξεχωριστό — μόνο για περιήγηση στο spec. Το integration σας συνεχίζει με τα service-account credentials.