Skip to main content
Every request must include a valid bearer token in the X-Auth-Token header. Tokens are issued via the OAuth 2.0 client credentials grant.

​
How it works

1

Get credentials

You receive a client_id and client_secret from Flow Payroll (see Obtaining credentials).
2

Exchange for a token

Your application exchanges those credentials for a short-lived access token at the token endpoint.
3

Call the API

Send the token in the X-Auth-Token header on every API request.
4

Refresh before expiry

When the token nears expiry, mint a fresh one. Do not call the token endpoint on every request.

​
Obtaining credentials

Client credentials are issued per integration. Contact your Flow Payroll account manager or hello@flowpayroll.ai to request a client_id / client_secret pair.
Treat client_secret like a password. Never embed it in client-side code, mobile apps, or public repositories. Rotate immediately if you suspect exposure.

​
Requesting a token

POST your credentials to the token endpoint using the standard OAuth 2.0 client credentials grant.
Response:
Cache the access_token in memory and reuse it until shortly before expires_in elapses.

​
Calling the API

Pass the token as X-Auth-Token on every request. If your credentials can access more than one organisation, also send X-Org-Id to choose which one the request applies to (see Choosing an organisation). Optionally include User-Id to attribute the call to a specific human user — this is recorded in audit logs but is not required for the request to succeed.

​
Choosing an organisation

One set of credentials can be granted access to many organisations — a bureau integration might serve hundreds. So the token proves who you are, not which organisation a request is for. You state the organisation per request with the X-Org-Id header (the id of the organisation you want to act on).
  • Access to one organisation: you can omit X-Org-Id — it’s resolved automatically.
  • Access to more than one: send X-Org-Id with the target organisation’s id. If you omit it, the request falls back to your configured default organisation; with no default set, it’s rejected so you choose explicitly.
  • Switching organisation is simply sending a different X-Org-Id — no new token, no re-authentication.
To discover which organisations your credentials can act on, call GET /v1/authentication/my-organisations.

​
Errors

​
Best practices

  • Cache tokens. Hitting the token endpoint per API call will rate-limit you and adds latency.
  • Refresh proactively. Renew when ~10% of the token’s lifetime remains, not after a 401.
  • Log the token’s jti claim, not the token itself, when correlating requests in your own observability.
  • Set User-Id when a request is initiated by an end user in your product, so the action is traceable in Flow Payroll’s audit log.