Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.flowpayroll.ai/llms.txt

Use this file to discover all available pages before exploring further.

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.
EnvironmentToken endpoint
Sandboxhttps://auth.sandbox.flowpayroll.ai/oauth2/token
Livehttps://auth.flowpayroll.ai/oauth2/token
curl -X POST https://auth.sandbox.flowpayroll.ai/oauth2/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": "eyJraWQiOiJ...",
  "expires_in": 3600,
  "token_type": "Bearer"
}
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. 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. 
GET /payrollconfig HTTP/1.1
Host: api.sandbox.flowpayroll.ai
X-Auth-Token: eyJraWQiOiJ...
User-Id: alice@example.com

​
Errors

StatusCauseWhat to do
401 UnauthorizedMissing, malformed, or expired X-Auth-TokenMint a fresh token and retry.
403 ForbiddenToken is valid but lacks access to the requested resourceVerify your credentials grant the scope you need.
429 Too Many RequestsRate limit hitBack off and retry; do not loop calling the token endpoint.

​
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.