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

# Grant a person one organisation

> Idempotent, and safe to use concurrently: two administrators adding two different organisations both succeed, where two declarative replaces would have one overwrite the other. No request body — the organisation is in the path, and reaching it is the whole grant, because everybody who reaches an organisation may do everything in it. 404 when the organisation is not yours.



## OpenAPI

````yaml /api-reference/specs/administration.json put /users/{principalId}/organisations/{organisationId}
openapi: 3.0.1
info:
  title: Administration API
  description: >-
    Manage your Flow Payroll account: the organisations it owns, the people who
    can sign in to it, the API tokens it holds, its brand, and a feed of recent
    administration activity. Every resource is scoped to the account your
    credentials belong to, so no request ever names a customer and the
    `X-Org-Id` header is not used.
  version: v1
servers:
  - url: https://api.sandbox.flowpayroll.ai/v1/administration
security:
  - X-Auth-Token: []
tags:
  - name: Customer
    description: >-
      Your account: the customer every other resource on this API belongs to.
      Read it and rename it.
  - name: Organisations
    description: >-
      The organisations your account owns: list them with headcounts and your
      access to each, get one in full, and add one or several at a time.
  - name: Users
    description: >-
      The people who can sign in to your account: list, invite (one or many),
      resend invitations, and manage each person's direct grants and
      account-wide access.
  - name: API tokens
    description: >-
      The client credentials your integrations authenticate with: create (the
      secret is shown once), rename, rotate, revoke, and manage which
      organisations each token reaches.
  - name: Activity
    description: Recent administration actions in your account, newest first.
paths:
  /users/{principalId}/organisations/{organisationId}:
    put:
      tags:
        - Users
      summary: Grant a person one organisation
      description: >-
        Idempotent, and safe to use concurrently: two administrators adding two
        different organisations both succeed, where two declarative replaces
        would have one overwrite the other. No request body — the organisation
        is in the path, and reaching it is the whole grant, because everybody
        who reaches an organisation may do everything in it. 404 when the
        organisation is not yours.
      operationId: GrantUserOrganisation
      parameters:
        - name: principalId
          in: path
          required: true
          schema:
            type: string
        - name: organisationId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserOrganisationsResponseResponseBody'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectResponseBody'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectResponseBody'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectResponseBody'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectResponseBody'
components:
  schemas:
    UserOrganisationsResponseResponseBody:
      type: object
      properties:
        message:
          $ref: '#/components/schemas/MessageWithTokenResponse'
        content:
          $ref: '#/components/schemas/UserOrganisationsResponseContentResponse'
        validationIssues:
          type: array
          items:
            $ref: '#/components/schemas/ValidationIssue'
          nullable: true
      additionalProperties: false
    ObjectResponseBody:
      type: object
      properties:
        message:
          $ref: '#/components/schemas/MessageWithTokenResponse'
        content:
          $ref: '#/components/schemas/ObjectContentResponse'
        validationIssues:
          type: array
          items:
            $ref: '#/components/schemas/ValidationIssue'
          nullable: true
      additionalProperties: false
    MessageWithTokenResponse:
      type: object
      properties:
        text:
          type: string
        token:
          type: string
        tokenArguments:
          type: array
          items:
            $ref: '#/components/schemas/ValidationIssueArgument'
          nullable: true
      additionalProperties: false
    UserOrganisationsResponseContentResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/UserOrganisationsResponse'
        metadata:
          $ref: '#/components/schemas/ContentMetadataResponse'
      additionalProperties: false
    ValidationIssue:
      type: object
      properties:
        field:
          type: string
        reason:
          type: string
        reasonToken:
          type: string
        reasonTokenArguments:
          type: array
          items:
            $ref: '#/components/schemas/ValidationIssueArgument'
          nullable: true
      additionalProperties: false
    ObjectContentResponse:
      type: object
      properties:
        data:
          nullable: true
        metadata:
          $ref: '#/components/schemas/ContentMetadataResponse'
      additionalProperties: false
    ValidationIssueArgument:
      type: object
      properties:
        name:
          type: string
        value:
          nullable: true
      additionalProperties: false
    UserOrganisationsResponse:
      type: object
      properties:
        principalId:
          type: string
          description: The person.
        organisationIds:
          type: array
          items:
            type: string
          description: Every organisation they hold a direct grant on.
        coversWholeCustomer:
          type: boolean
          description: >-
            Whether they also hold account-wide access, which reaches every
            organisation the account owns,

            including ones added later. Read this before treating an empty list
            as no access. Nothing on the

            organisations collection can create or remove it.
      additionalProperties: false
      description: The organisations one person reaches, after a read or a change.
    ContentMetadataResponse:
      type: object
      properties:
        dateFormat:
          type: string
        dateTimeFormat:
          type: string
        paginationToken:
          type: string
          nullable: true
      additionalProperties: false
  securitySchemes:
    X-Auth-Token:
      type: apiKey
      description: FlowPayroll JWT (raw token, no Bearer prefix)
      name: X-Auth-Token
      in: header

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.