Skip to main content
The Authentication API exposes the identity-scoped data behind your access token — currently, the organisations you are entitled to act on. One set of credentials can be granted access to many organisations (a bureau integration might serve hundreds), and this API is how you find out which ones yours covers. Call it right after you mint your first token, and again whenever your organisation grants may have changed. This page covers what the endpoints do. How to obtain credentials, mint tokens, and send the X-Auth-Token and X-Org-Id headers is covered on the Authentication page. All endpoints sit under the /v1/authentication base path, relative to the environment base URLs documented on the API reference introduction.

​
Key concepts

  • Principal — the authenticated identity behind a token: either a user or a machine-to-machine (M2M) client. The principal authenticates once; each request then states which organisation it applies to.
  • Organisation grant — an entitlement linking a principal to an organisation it can act on. Grants are managed by Flow Payroll and are the source of truth for who can access which organisation.
  • Organisation id — the identifier returned for each organisation. Send it as the X-Org-Id header on subsequent requests to other Flow Payroll APIs to scope them to that organisation.
  • Pagination token — an opaque cursor returned alongside a page of results. Pass it back to fetch the next page; when it is absent, you have the full list.

​
API structure

​
Organisations

GET /my-organisations lists every organisation the authenticated principal has been granted access to, with each organisation’s id, registered legal name, and trading name. Results are paginated: set pageSize (1–100, default 50) and follow paginationToken until it is no longer returned.
This endpoint works before an organisation is selected — you do not send X-Org-Id to call it. That makes it the natural source for an organisation picker in your own product, and the first call a multi-organisation integration makes after minting a token.

​
Typical workflow

  1. Mint an access token with your client credentials — see Authentication.
  2. Call GET /my-organisations with the token to list the organisations you can act on.
  3. If the response includes a paginationToken, pass it back as the paginationToken query parameter and repeat until it is absent.
  4. Pick the target organisation and send its organisationId as the X-Org-Id header on your calls to the other Flow Payroll APIs.
  5. Refresh the list periodically, or when a request is rejected for organisation access, rather than hard-coding organisation ids — your grants can change over time.

​
Notes and best practices

  • pageSize accepts 1–100 and defaults to 50; values outside the range are clamped rather than rejected.
  • Treat paginationToken as opaque. Sending a token that is not valid returns a 400 response.
  • legalName can be null if the organisation directory has no record for the organisation yet, and tradingName is only set when it differs from the legal name — handle both when displaying organisation names.
  • Cache one token and reuse it across all your organisations. Switching organisation is a header change on the next request, not a new token.

​
Authentication

Every request must carry a valid token in the X-Auth-Token header; because this API returns identity-scoped data, it is the one part of the platform you call without X-Org-Id — see Authentication for the full header semantics. Responses use the shared envelope described in Response format.