Authentication

Overview

The Merion API uses OpenID Connect (OIDC) for authentication. The identity provider is at auth.merion.com.au. All authenticated API calls require a short-lived Bearer token obtained through the OIDC authorisation code flow with PKCE (S256).

PKCE (Proof Key for Code Exchange) prevents authorisation code interception attacks without requiring a long-lived client secret. The S256 challenge method (SHA-256) is required — plain PKCE is rejected.

Access is by arrangement. To request credentials, email [email protected] with the subject line "API Access Request". See Getting Started for what to include in your request.

Discovery document

Rather than hardcoding endpoint URLs, fetch the OIDC discovery document at startup and read the endpoint URLs from it:

GET https://auth.merion.com.au/.well-known/openid-configuration

The discovery document contains authorization_endpoint, token_endpoint, userinfo_endpoint, jwks_uri, and other configuration. See OIDC Discovery for the full field reference.

Algorithm

All ID tokens are signed using ES256 — ECDSA with the P-256 curve and SHA-256. The public signing keys are served at the jwks_uri in the discovery document. Your OIDC library should verify the token signature automatically using those keys.

PKCE flow step by step

1. Generate a code_verifier. This is a cryptographically random string, 43–128 characters, URL-safe Base64 (characters A-Z, a-z, 0-9, -, _, ., ~). Do not store it in browser storage accessible to JavaScript — use a server-side flow or a confidential client where the verifier is kept server-side.
2. Compute the code_challenge.

   code_challenge = BASE64URL(SHA256(ASCII(code_verifier)))

   Most OIDC libraries compute this for you when you specify code_challenge_method=S256.
3. Redirect the user to the authorization_endpoint with these query parameters:

   response_type

   code

   client_id

   Your assigned client ID

   redirect_uri

   Your registered callback URL

   scope

   openid profile

   code_challenge

   The computed challenge (step 2)

   code_challenge_method

   S256

   state

   A random, unguessable value — you will verify this on return

4. User authenticates at auth.merion.com.au.
5. Auth server redirects back to your redirect_uri with code and state query parameters.
6. Verify the state parameter matches the value you sent. Reject the response if it does not match — this is your CSRF protection.
7. Exchange the authorisation code for tokens. POST to the token_endpoint (read from the discovery document):

   curl -s -X POST https://auth.merion.com.au/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=authorization_code" \
     -d "code=<authorization_code>" \
     -d "redirect_uri=<your_redirect_uri>" \
     -d "client_id=<your_client_id>" \
     -d "code_verifier=<your_code_verifier>"

   The token_endpoint URL shown above is illustrative — always read it from the discovery document, not hardcoded.

8. Receive the token response. A successful exchange returns:

   access_token

   Short-lived JWT; use as the Bearer token

   id_token

   Signed JWT with identity claims; validate before trusting

   refresh_token

   Long-lived; use to obtain new access tokens without re-authentication (if configured)

   expires_in

   Seconds until the access token expires; treat this value as authoritative

9. Use the access token. Include it as a Bearer token on all authenticated API requests:

   Authorization: Bearer <access_token>

Refreshing tokens

Access tokens are short-lived. Before the access token expires (use expires_in to track expiry), use the refresh token to obtain a new access token:

curl -s -X POST <token_endpoint> \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=<your_refresh_token>" \
  -d "client_id=<your_client_id>"

Rotate refresh tokens on use — treat the refresh token from the response as the new one. Do not reuse refresh tokens across multiple concurrent requests.

Validating ID tokens

Validate the ID token before trusting any of its claims:

1. Fetch the public keys from the jwks_uri in the discovery document.
2. Verify the token signature using the key matching the kid header claim.
3. Verify the iss claim equals https://auth.merion.com.au.
4. Verify the aud claim equals your client_id.
5. Verify the exp claim has not passed (token has not expired).

Most OIDC client libraries handle all of these checks automatically when you call their validation function. Do not skip validation in production code.

Requesting access

API access is by arrangement. Email [email protected] with the subject line "API Access Request". Include your use case, the integration you are building, and your relationship with Merion. Upon approval you will receive a client ID and onboarding steps.