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

# List the organisations the authenticated principal can act on

> Returns every organisation the caller has been granted access to, with its legal and trading name. The list is sourced from the principal access table (the source of truth for who can act on which organisation) and joined with the organisation directory for names. Works before an organisation is selected, so a multi-organisation principal can populate an organisation switcher. Results are paginated; follow `paginationToken` until it is absent.



## OpenAPI

````yaml /api-reference/specs/authentication.json get /my-organisations
openapi: 3.0.1
info:
  title: Authentication Service
  description: >-
    Identity and organisation-access API for FlowPayroll. The signed-in
    principal (a user or an M2M client) authenticates once; per-request
    organisation scope is supplied via the X-Org-Id header to each service. This
    API exposes the principal's identity-scoped data — currently the
    organisations they are entitled to act on.
  contact:
    name: FlowPayroll
    email: support@flowpayroll.com
  version: v1
servers:
  - url: https://api.sandbox.flowpayroll.ai/v1/authentication
security:
  - X-Auth-Token: []
paths:
  /my-organisations:
    get:
      tags:
        - Organisations
      summary: List the organisations the authenticated principal can act on
      description: >-
        Returns every organisation the caller has been granted access to, with
        its legal and trading name. The list is sourced from the principal
        access table (the source of truth for who can act on which organisation)
        and joined with the organisation directory for names. Works before an
        organisation is selected, so a multi-organisation principal can populate
        an organisation switcher. Results are paginated; follow
        `paginationToken` until it is absent.
      operationId: GetMyOrganisations
      parameters:
        - name: pageSize
          in: query
          required: false
          description: >-
            Maximum number of organisations to return (1-100). Defaults to 50;
            values outside the range are clamped.
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 50
        - name: paginationToken
          in: query
          required: false
          description: Opaque token returned by a previous page. Omit for the first page.
          schema:
            type: string
      responses:
        '200':
          description: The organisations the caller can act on.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseMyOrganisations'
        '400':
          description: The pagination token is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
        '401':
          description: The caller could not be authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
components:
  schemas:
    ApiResponseMyOrganisations:
      type: object
      properties:
        content:
          $ref: '#/components/schemas/ContentMyOrganisations'
        metadata:
          $ref: '#/components/schemas/Metadata'
        errors:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/Error'
        message:
          $ref: '#/components/schemas/Message'
    ApiResponseError:
      type: object
      properties:
        content:
          nullable: true
        metadata:
          $ref: '#/components/schemas/Metadata'
        errors:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/Error'
        message:
          $ref: '#/components/schemas/Message'
    ContentMyOrganisations:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/MyOrganisationsData'
        metadata:
          $ref: '#/components/schemas/Metadata'
    Metadata:
      type: object
      properties:
        dateFormat:
          type: string
          nullable: true
        dateTimeFormat:
          type: string
          nullable: true
    Error:
      type: object
      properties:
        field:
          type: string
          nullable: true
        reasonText:
          type: string
          nullable: true
        reasonId:
          type: string
          nullable: true
        reasonParameters:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/Pair'
    Message:
      type: object
      properties:
        text:
          type: string
          nullable: true
        textId:
          type: string
          nullable: true
        textParameters:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/Pair'
    MyOrganisationsData:
      type: object
      properties:
        organisations:
          type: array
          items:
            $ref: '#/components/schemas/MyOrganisation'
        paginationToken:
          type: string
          nullable: true
          description: >-
            Pass back as `paginationToken` to fetch the next page. Null when
            there are no more pages.
    Pair:
      type: object
      properties:
        key:
          type: string
          nullable: true
        value:
          type: string
          nullable: true
    MyOrganisation:
      type: object
      properties:
        organisationId:
          type: string
          description: >-
            The organisation identifier to send as the X-Org-Id header on
            subsequent requests.
        legalName:
          type: string
          nullable: true
          description: >-
            Registered legal name. Null if the organisation directory has no
            record yet.
        tradingName:
          type: string
          nullable: true
          description: Trading (display) name, if different from the legal name.
  securitySchemes:
    X-Auth-Token:
      type: apiKey
      description: Cognito access token (raw JWT, no `Bearer` prefix).
      name: X-Auth-Token
      in: header

````