API Quickstart

How to authenticate against Keycloak and call an Olly API through the gateway. The full per-service endpoint reference is in the API Docs (Scalar); this page is the auth + first-call walkthrough.

The shape of it

Every API call is a bearer-token request through one gateway:

client  ──(1) get token──▶  Keycloak (auth.dev.hiolly.com, realm `olly`)
client  ──(2) Bearer call─▶  APISIX gateway (api.dev.hiolly.com)  ──▶  Go service

There is a single realm, olly. Clients and their grant types:

Client	Grant	Notes
web-member	ROPC (password)	member app; carries the party_locator claim
mobile-app	direct grant (password)	mobile
web-employer	PKCE (auth code) only	employer app; cannot do a password grant
web-admin	direct grant	admin console

Service-to-service calls use the client-credentials grant against the same token endpoint, not a password.

Step 1: get a token

web-member and mobile-app accept the password grant, so you can get a token with one curl. All test users use the password Olly2026.

curl -s -X POST https://auth.dev.hiolly.com/realms/olly/protocol/openid-connect/token \
  -d grant_type=password \
  -d client_id=web-member \
  -d username=member@olldemo.co.uk \
  -d password=Olly2026 \
  -d scope=openid

The response is the standard Keycloak token JSON; the access_token is what you send as a bearer (TTL is 15 minutes):

{ "access_token": "eyJ...", "token_type": "Bearer", "expires_in": 900,
  "refresh_token": "eyJ...", "id_token": "eyJ...", "scope": "openid ..." }

Step 2: call the API through the gateway

The gateway is https://api.dev.hiolly.com. Routes are prefixed by service and the gateway strips the prefix before forwarding, so GET /provider/providers reaches the provider service's GET /providers.

TOKEN=$(curl -s -X POST https://auth.dev.hiolly.com/realms/olly/protocol/openid-connect/token \
  -d grant_type=password -d client_id=web-member \
  -d username=member@olldemo.co.uk -d password=Olly2026 -d scope=openid \
  | python3 -c 'import sys,json; print(json.load(sys.stdin)["access_token"])')

curl -s https://api.dev.hiolly.com/provider/providers -H "Authorization: Bearer $TOKEN"

List endpoints return a JSON array of resource objects; check the API Docs for each service's exact schema.

Gateway route prefixes

Prefix	Service	Port
/claims/*	claims	4001
/eligibility/*	eligibility	4002
/enrollment/*	enrollment	4003
/billing/*	billing	4004
/provider/*	provider	4005
/notifications/*	notifications	4006
/policy-admin/*	policy-admin	4007
/group-scheme/*	group-scheme	4010
/broker-api/*	broker	4011
/member-portal/*	member-portal	4012

Troubleshooting

• 502 from the gateway on the shared dev box. The dev APISIX upstreams are being re-pointed after the Go services moved from dev-1 to dev-2; gateway calls (Step 2) may 502 until that lands. Step 1 (the token) works regardless. If you need a service directly, hit it on dev-2.
• invalid_grant: Account is not fully set up. That test user has a pending Keycloak required action (verify email / update password). Clear it in the Keycloak admin console, or use a fully provisioned member user. The password is still Olly2026.
• invalid_client with web-employer. It is PKCE-only and rejects the password grant. Use web-member or mobile-app for a copy-paste token.