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

# Authentication API overview

> Discover the organisations your credentials can act on, so you can scope every other Flow Payroll API request to the right organisation.

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](/api-reference/authentication) page.

All endpoints sit under the `/v1/authentication` base path, relative to the environment base URLs documented on the [API reference introduction](/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.

<Note>
  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.
</Note>

## Typical workflow

1. Mint an access token with your client credentials — see [Authentication](/api-reference/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](/api-reference/authentication) for the full header semantics. Responses use the shared envelope described in [Response format](/api-reference/response-format).