Getting Started

Authentication

1 min read

How the Airfree platform authenticates requests: OpenID Connect via Keycloak, Authorization Code with PKCE for browser apps, and bearer-token validation at the edge.

The Airfree platform authenticates every request through a central OpenID Connect provider. All API traffic passes through the platform edge, which validates the token, rejects anything unauthenticated with 401, and forwards trusted identity headers to the service behind it.

Choose the right flow

Pick the OAuth 2.0 flow that matches where your code runs.

Browser / single-page apps: Authorization Code flow with PKCE, using a public client. Never embed a client secret in browser code.
Server-to-server / backend jobs: client-credentials grant, using a confidential client with a secret held server-side.
Mobile / native apps: Authorization Code flow with PKCE and a system browser.

Authorization Code with PKCE

A browser client generates a random code verifier, derives an S256 challenge, and redirects the user to the authorize endpoint. After sign-in, the returned code is exchanged — with the original verifier — for tokens. PKCE means no secret is ever exposed to the browser.

GET https://airfree.au/auth/realms/airfree/protocol/openid-connect/auth
  ?response_type=code
  &client_id=your-web-client
  &redirect_uri=https://your-app.example/callback
  &scope=openid profile email
  &code_challenge=<S256(code_verifier)>
  &code_challenge_method=S256
  &state=<opaque>

Derive the base URL and redirect URI from window.location.origin at runtime. A build-time absolute URL bakes in the wrong host and breaks logins from any other origin.

Calling the API

Send the access token as a bearer credential on every request. The edge validates the signature and issuer, then injects X-Auth-* identity headers for the upstream service. Tokens are short-lived; use the refresh token (browser flows) or request a new one (client credentials) when they expire.

GET /api/v1/cadastre/parcels HTTP/1.1
Host: airfree.au
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Status codes you will see

200 — authenticated and authorised.
401 — missing, expired, or invalid token.
403 — valid token, but the identity lacks the role required for that resource.

All documentation Need help? Contact us