> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ctrl-hub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a grant

> Create a new grant



## OpenAPI

````yaml /api-reference/openapi.yaml post /v3/grants
openapi: 3.1.0
info:
  contact:
    email: support@ctrl-hub.com
    name: Ctrl Hub
    url: https://www.ctrl-hub.com
  description: >
    Ctrl Hub is the all-in-one platform for high-risk industries like utilities,
    construction, infrastructure, and renewables. We help teams manage
    everything from risk assessments and HAVS exposure to vehicle and equipment
    checks, with a guaranteed minimum of 200% ROI.
  license:
    name: MIT License
    url: https://opensource.org/licenses/MIT
  summary: An API for managing your compliance and risk posture
  termsOfService: https://www.ctrl-hub.com/terms-conditions
  title: Ctrl Hub
  version: 1.0.0
servers:
  - description: Production
    url: https://api.ctrl-hub.com
  - description: Staging
    url: https://api.ctrl-hub.dev
  - description: Development
    url: https://api.ctrl-hub.run
security: []
tags:
  - description: |
      Audit events are the events that are logged by the system.
    name: Audit Events
  - description: |
      View the platform's health and availability.
    name: Status
  - description: >
      User-owned dashboards composed of cards on a fixed-slot bento layout.
      Cards come from a per-domain registry; the API stores their config as
      opaque JSON.
    name: Dashboards
  - description: |
      Manage appointments for work to be carried out with your customers
    name: Customer Appointments
  - description: |
      Manage interactions you have with your customers
    name: Customer Interactions
  - description: |
      Manage accounts for your customers
    name: Customer Accounts and Contacts
  - description: |
      Qualifications are the skills and knowledge that an organisation requires.
    name: Qualifications
  - description: |
      Workflows allow you to automate your processes.
    name: Workflows
  - description: |
      Manage documents
    name: Documents
  - description: |
      Manage documents
    name: Folders
  - description: |
      Manage documents
    name: Document Reviews
  - description: |
      Manage feature configurations for an organisation.
    name: Feature Configurations
  - description: |
      Equipment are the physical assets that an organisation manages.
    name: Equipment
  - description: |
      Manage your forms and their schemas
    name: Forms, Schemas and Categories
  - description: |
      Create and view form submissions
    name: Submissions
  - description: |
      View the roles available in the system.
    name: IAM Roles
  - description: >
      IAM role groups can be assigned to principals to manage authorisation
      centrally.
    name: IAM Role Groups
  - description: |
      Manage service accounts which can access the API programmatically.
    name: Service Accounts
  - description: |
      Manage bridges between organisations.
    name: Bridges
  - description: |
      Manage settings for an organisation.
    name: Settings
  - description: |
      Manage teams within an organisation.
    name: Teams
  - description: |
      Manage job roles within an organisation.
    name: Job Roles
  - description: |
      Manage users and accounts.
    name: Users
  - description: |
      Invite and manage invitations to organisations.
    name: Invitations
  - description: >
      IAM grants are the asignment of roles or permissions to principals to
      manage resource access.
    name: IAM Grants
  - description: |
      View the permissions available in the system.
    name: IAM Permissions
  - description: |
      SSO providers are the identity providers for an organisation.
    name: SSO Providers
  - description: |
      Whoami returns information about the currently authenticated principal.
    name: Whoami
  - description: |
      Manage your images
    name: Images
  - description: >
      Organisations are the center point for most resources in the platform.
      Most other endpoints are subresources of an organisation.
    name: Organisations
  - description: |
      Permits managements, integrated with street manager.
    name: Permits
  - description: |
      Projects manage your work and governance.
    name: Projects
  - description: >
      Import templates allow users to save and reuse their CSV importer
      configuration as named templates.
    name: Import Templates
  - description: |
      Properties are the physical locations.
    name: Properties
  - description: |
      Search across schemes, work orders, and operations.
    name: Search
  - description: |
      Provides the API specification in JSON and YAML formats
    name: Specifications
  - description: |
      Streets are the physical roads.
    name: Streets
  - description: |
      Integration with street manager
    name: Street Manager
  - description: |
      Vehicles are the physical vehicles that an organisation manages.
    name: Vehicles
  - description: >
      Scheme contracts (also known as regions) group schemes allocated from the
      network to a contractor.
    name: Scheme Contracts
  - description: >
      Scheme shares allow you to share your schemes with other organisations
      across bridges.
    name: Scheme Shares
  - description: |
      Schemes are large programmes of work
    name: Schemes
  - description: |
      Work orders the component parts of a scheme.
    name: Work Orders
  - description: |
      Operations are the work to be carried out within work orders.
    name: Operations
externalDocs:
  description: More documentation and resources
  url: https://docs.ctrl-hub.com
paths:
  /v3/grants:
    post:
      tags:
        - IAM Grants
      summary: Create a grant
      description: Create a new grant
      operationId: CreateGrant
      requestBody:
        $ref: '#/components/requestBodies/CreateGrant'
      responses:
        '201':
          $ref: '#/components/responses/GetGrant'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - Session: []
        - OAuth2: []
        - Cookie: []
components:
  requestBodies:
    CreateGrant:
      required: true
      description: The grant to create.
      content:
        application/vnd.api+json:
          schema:
            type: object
            required:
              - data
            properties:
              data:
                type: object
                required:
                  - type
                  - attributes
                  - relationships
                properties:
                  type:
                    type: string
                    const: grants
                  attributes:
                    type: object
                    required:
                      - type
                      - subject
                      - scope
                      - reason
                    properties:
                      type:
                        type: string
                        enum:
                          - role
                          - permission
                      subject:
                        type: string
                      scope:
                        type: object
                        required:
                          - attributes
                          - patterns
                        properties:
                          attributes:
                            type: array
                            items:
                              type: object
                              required:
                                - name
                                - operation
                                - value
                              properties:
                                name:
                                  type: string
                                operation:
                                  type: string
                                  enum:
                                    - '='
                                    - '!='
                                    - '>'
                                    - <
                                    - '>='
                                    - <=
                                value:
                                  type: string
                          patterns:
                            type: array
                            items:
                              type: object
                              required:
                                - name
                                - matcher
                                - operation
                                - value
                              properties:
                                name:
                                  type: string
                                matcher:
                                  type: string
                                  enum:
                                    - prefix
                                    - suffix
                                    - contains
                                operation:
                                  type: string
                                  enum:
                                    - '='
                                    - '!='
                                value:
                                  type: string
                      reason:
                        type: string
                      starts_at:
                        type: string
                        format: date-time
                      expires_at:
                        type: string
                        format: date-time
                  relationships:
                    type: object
                    required:
                      - organisation
                    properties:
                      organisation:
                        type: object
                        required:
                          - data
                        properties:
                          data:
                            type: object
                            required:
                              - type
                              - id
                            properties:
                              type:
                                type: string
                                const: organisations
                              id:
                                type: string
                                description: The ID of the organisation.
  responses:
    GetGrant:
      description: Get a grant.
      headers:
        Content-Type:
          $ref: '#/components/headers/content-type'
        Content-Length:
          $ref: '#/components/headers/content-length'
        X-Request-ID:
          $ref: '#/components/headers/x-request-id'
      content:
        application/vnd.api+json:
          schema:
            allOf:
              - type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/Grant'
                  included:
                    $ref: '#/components/schemas/GrantIncludes'
              - $ref: '#/components/schemas/JSONAPI'
    BadRequest:
      description: >
        There was an error with the request - this could be due to an invalid
        body, query parameters,

        or headers that were sent to the API.
      headers:
        Content-Type:
          $ref: '#/components/headers/content-type'
        Content-Length:
          $ref: '#/components/headers/content-length'
        X-Request-ID:
          $ref: '#/components/headers/x-request-id'
      content:
        application/vnd.api+json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/Error'
          example:
            id: 98ca4a78-b66f-4234-9719-aaf832ee6669
            status: '400'
            title: A validation error was encountered
            source:
              parameter: include
            meta:
              resource: wrong_value
    Unauthorised:
      description: Authentication failed
      headers:
        Content-Type:
          $ref: '#/components/headers/content-type'
        Content-Length:
          $ref: '#/components/headers/content-length'
        X-Request-ID:
          $ref: '#/components/headers/x-request-id'
      content:
        application/vnd.api+json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/Error'
          example:
            id: 05fc9c8d-73b9-4697-9337-57f7a567a48f
            status: '401'
            title: You are not authorised to access this resource
            detail: In order to access this resource, you need the 'admin' role.
            code: AUTH.001
    Conflict:
      description: The request conflicts with the current state of the resource
      headers:
        Content-Type:
          $ref: '#/components/headers/content-type'
        Content-Length:
          $ref: '#/components/headers/content-length'
        X-Request-ID:
          $ref: '#/components/headers/x-request-id'
      content:
        application/vnd.api+json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/Error'
          example:
            id: 8e2f9a34-b5c6-4d7e-9f8a-2b3c4d5e6f7g
            status: '409'
            title: Conflict
            detail: The request conflicts with the current state of the resource.
            code: CONFLICT.001
    InternalServerError:
      description: There was a problem handling the request on the server side
      headers:
        Content-Type:
          $ref: '#/components/headers/content-type'
        Content-Length:
          $ref: '#/components/headers/content-length'
        X-Request-ID:
          $ref: '#/components/headers/x-request-id'
      content:
        application/vnd.api+json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/Error'
          example:
            id: fe9d9a69-f0a7-4fdc-bb2c-176027f316c5
            status: '500'
            title: Internal Server Error
            detail: An unexpected error occurred on the server.
  headers:
    content-type:
      description: The content type of the response
      schema:
        type: string
      example: application/vnd.api+json
    content-length:
      description: The length of the response body in bytes
      schema:
        type: integer
        format: int32
      example: 1234
    x-request-id:
      description: >-
        An ID that can be provided when reporting bugs to help identify the
        issue
      schema:
        type: string
      example: 8470f56af4cf25e22be08e72c70dbbdc
  schemas:
    Grant:
      type: object
      description: A grant
      required:
        - id
        - type
        - attributes
        - meta
        - relationships
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the grant.
        type:
          type: string
          const: grants
        attributes:
          $ref: '#/components/schemas/GrantAttributes'
        meta:
          $ref: '#/components/schemas/GrantMeta'
        relationships:
          $ref: '#/components/schemas/GrantRelationships'
    GrantIncludes:
      type: array
      description: Related resources that can be included when a grant is returned
      items:
        discriminator:
          propertyName: type
          mapping:
            organisations:
              $ref: '#/components/schemas/Organisation'
            role-groups:
              $ref: '#/components/schemas/RoleGroup'
            service-accounts:
              $ref: '#/components/schemas/ServiceAccount'
            scheme-shares:
              $ref: '#/components/schemas/SchemeShare'
            teams:
              $ref: '#/components/schemas/Team'
            users:
              $ref: '#/components/schemas/User'
        oneOf:
          - $ref: '#/components/schemas/Organisation'
          - $ref: '#/components/schemas/RoleGroup'
          - $ref: '#/components/schemas/ServiceAccount'
          - $ref: '#/components/schemas/SchemeShare'
          - $ref: '#/components/schemas/Team'
          - $ref: '#/components/schemas/User'
    JSONAPI:
      type: object
      description: JSON API response object
      required:
        - jsonapi
      properties:
        jsonapi:
          type: object
          required:
            - version
          properties:
            version:
              type: string
              description: The version of the JSON API specification
              examples:
                - '1.0'
    Error:
      type: object
      description: An error response
      properties:
        id:
          description: >-
            A unique identifier for this particular occurrence of the problem.
            If you encounter this, please provide us with the error ID and we
            can investigate it on our side.
          type: string
          format: uuid
          examples:
            - 05fc9c8d-73b9-4697-9337-57f7a567a48f
        status:
          description: >-
            The status code for the error. This might not match the HTTP status
            code if there are more that one errors to return with different
            status codes.
          type: string
          examples:
            - '401'
            - '500'
        title:
          description: A human readable title for the error.
          type: string
          examples:
            - You are not authorised to access this resource
        detail:
          description: >-
            Where there is more detail that we can provide outside of the title,
            we will provide it here.
          type: string
          examples:
            - In order to access this resource, you need the 'admin' role.
        code:
          description: >-
            A unique code for the error that may help us to diagnose the issue.
            Not all errors have codes, so this is usually empty.
          type: string
          examples:
            - AUTH.001
        source:
          description: A JSON object containing additional information about the error.
          type: object
          properties:
            pointer:
              description: >-
                A JSON Pointer to the value in the request that caused the
                error.
              type: string
              examples:
                - /data/attributes/email
            parameter:
              description: >-
                A string indicating which query parameter in the request caused
                the error.
              type: string
              examples:
                - include
      required:
        - id
        - status
        - title
    GrantAttributes:
      type: object
      description: Attributes of a grant
      required:
        - type
        - subject
        - scope
        - reason
        - expires_at
      properties:
        type:
          type: string
          enum:
            - role
            - permission
        subject:
          type: string
        scope:
          type: object
          required:
            - attributes
            - patterns
          properties:
            attributes:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  operation:
                    type: string
                    enum:
                      - '='
                      - '!='
                      - '>'
                      - <
                      - '>='
                      - <=
                  value:
                    type: string
            patterns:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  matcher:
                    type: string
                    enum:
                      - prefix
                      - suffix
                      - contains
                  operation:
                    type: string
                    enum:
                      - '='
                      - '!='
                  value:
                    type: string
        reason:
          type: string
        starts_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
    GrantMeta:
      type: object
      description: Metadata for a grant
      required:
        - created_at
      properties:
        created_at:
          type: string
          format: date-time
          description: The date and time when the grant was created
        grantee_type:
          type: string
          description: >-
            The type of grantee this grant is for. The grantee is in the grant
            relationships.
          enum:
            - groups
            - job-roles
            - service-accounts
            - scheme-shares
            - teams
            - users
    GrantRelationships:
      type: object
      description: Relationships for a grant
      required:
        - organisation
        - authoriser
      properties:
        organisation:
          type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/OrganisationRelationship'
        authoriser:
          type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/UserRelationship'
        principal_job_role:
          type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/JobRoleRelationship'
        principal_role_group:
          type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/RoleGroupRelationship'
        principal_service_account:
          type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/ServiceAccountRelationship'
        principal_scheme_share:
          type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/SchemeShareRelationship'
        principal_team:
          type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/TeamRelationship'
        principal_user:
          type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/UserRelationship'
    Organisation:
      type: object
      description: An organisation
      required:
        - id
        - type
        - attributes
        - meta
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the organisation.
        type:
          type: string
          const: organisations
        attributes:
          $ref: '#/components/schemas/OrganisationAttributes'
        meta:
          $ref: '#/components/schemas/OrganisationMeta'
        relationships:
          $ref: '#/components/schemas/OrganisationRelationships'
    RoleGroup:
      type: object
      description: A role group
      required:
        - id
        - type
        - attributes
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the group.
        type:
          type: string
          const: groups
        attributes:
          $ref: '#/components/schemas/RoleGroupAttributes'
        relationships:
          $ref: '#/components/schemas/RoleGroupRelationships'
    ServiceAccount:
      type: object
      description: A service account
      required:
        - id
        - type
        - attributes
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the service account.
        type:
          type: string
          const: service-accounts
        attributes:
          $ref: '#/components/schemas/ServiceAccountAttributes'
        meta:
          $ref: '#/components/schemas/ServiceAccountMeta'
        relationships:
          $ref: '#/components/schemas/ServiceAccountRelationships'
    SchemeShare:
      type: object
      description: A scheme share
      required:
        - id
        - type
        - attributes
        - relationships
        - meta
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the scheme share.
        type:
          type: string
          const: scheme-shares
        attributes:
          $ref: '#/components/schemas/SchemeShareAttributes'
        relationships:
          $ref: '#/components/schemas/SchemeShareRelationships'
        meta:
          $ref: '#/components/schemas/SchemeShareMeta'
    Team:
      type: object
      description: A team
      required:
        - id
        - type
        - attributes
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the team.
        type:
          type: string
          const: teams
        attributes:
          $ref: '#/components/schemas/TeamAttributes'
        meta:
          $ref: '#/components/schemas/TeamMeta'
        relationships:
          $ref: '#/components/schemas/TeamRelationships'
    User:
      type: object
      description: A user
      required:
        - id
        - type
        - attributes
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the user.
          examples:
            - 123e4567-e89b-12d3-a456-426614174000
        type:
          type: string
          const: users
        attributes:
          $ref: '#/components/schemas/UserAttributes'
        meta:
          $ref: '#/components/schemas/UserMeta'
        relationships:
          $ref: '#/components/schemas/UserRelationships'
    OrganisationRelationship:
      type: object
      description: Represents a relationship to an organisation
      required:
        - id
        - type
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the organisation
        type:
          type: string
          const: organisations
    UserRelationship:
      type: object
      description: Represents a relationship to a user
      required:
        - id
        - type
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the user
        type:
          type: string
          const: users
    JobRoleRelationship:
      type: object
      description: Represents a relationship to a job role
      required:
        - id
        - type
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the job role
        type:
          type: string
          const: job-roles
    RoleGroupRelationship:
      type: object
      description: Represents a relationship to a role group
      required:
        - id
        - type
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the role group
        type:
          type: string
          const: role_groups
    ServiceAccountRelationship:
      type: object
      description: Represents a relationship to a service account
      required:
        - id
        - type
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the service account
        type:
          type: string
          const: service-accounts
    SchemeShareRelationship:
      type: object
      description: Represents a relationship to a scheme share
      required:
        - id
        - type
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the scheme share
        type:
          type: string
          const: scheme-shares
    TeamRelationship:
      type: object
      description: Represents a relationship to a team
      required:
        - id
        - type
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the team
        type:
          type: string
          const: teams
    OrganisationAttributes:
      type: object
      description: Attributes for an organisation
      required:
        - name
        - slug
        - sandbox
      properties:
        name:
          type: string
          description: The name of the organisation.
          examples:
            - Acme Construction Ltd
        slug:
          type: string
          description: The URL-friendly identifier for the organisation.
          examples:
            - acme-construction
        description:
          type: string
          description: A short description of the organisation.
          examples:
            - >-
              Leading construction company specializing in infrastructure
              projects
        sandbox:
          type: boolean
          description: Whether the organisation is a sandbox (i.e. a test organisation)
          examples:
            - false
        settings:
          type: object
    OrganisationMeta:
      type: object
      description: Meta information for an organisation
      required:
        - v3
        - status
      properties:
        created_at:
          type: string
          format: date-time
          description: The creation time of the organisation.
          examples:
            - '2023-01-15T10:30:00.000Z'
        updated_at:
          type: string
          format: date-time
          description: The last update time of the organisation.
          examples:
            - '2023-02-20T14:45:00.000Z'
        v3:
          type: boolean
          description: Whether the organisation is using version 3 exclusively.
          examples:
            - true
        status:
          type: string
          enum:
            - active
            - inactive
          default: active
          description: The current status of the organisation.
          examples:
            - active
        features:
          type: array
          description: Available features and their limits for the organisation.
          items:
            type: object
            properties:
              name:
                type: string
                description: The name of the feature.
                examples:
                  - advanced_reporting
              enabled:
                type: boolean
                description: Whether the feature is enabled.
                examples:
                  - true
              limit:
                type: integer
                description: The usage limit for this feature (if applicable).
                examples:
                  - 1000
    OrganisationRelationships:
      type: object
      description: Relationships for an organisation
      properties:
        users:
          type: object
          required:
            - data
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/UserRelationship'
        service_accounts:
          type: object
          required:
            - data
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/ServiceAccountRelationship'
        groups:
          type: object
          required:
            - data
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/UserGroupRelationship'
        teams:
          type: object
          required:
            - data
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/TeamRelationship'
        nomenclature:
          type: object
          required:
            - data
          properties:
            data:
              oneOf:
                - $ref: '#/components/schemas/NomenclatureRelationship'
                - type: 'null'
    RoleGroupAttributes:
      type: object
      description: Attributes for a group
      required:
        - name
      properties:
        name:
          type: string
          description: The group name.
          examples:
            - Site Managers
        description:
          type: string
          description: A description of the group.
          examples:
            - Group for site management personnel with full scheme access
    RoleGroupRelationships:
      type: object
      description: Relationships for a group
      properties:
        service_accounts:
          type: object
          required:
            - data
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/ServiceAccountRelationship'
        users:
          type: object
          required:
            - data
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/UserRelationship'
    ServiceAccountAttributes:
      type: object
      description: Attributes for a service account
      properties:
        name:
          type: string
          description: The name of the service account.
          examples:
            - API Integration Service
        description:
          type: string
          description: A description of the service account.
          examples:
            - Service account for third-party API integration
        email:
          type: string
          format: email
          description: The email of the service account.
          examples:
            - api-service@example.com
        enabled:
          type: boolean
          description: Whether the service account is active.
          examples:
            - true
        keys:
          type: array
          description: API keys associated with this service account.
          items:
            type: object
            required:
              - id
            properties:
              id:
                type: string
                format: uuid
                description: The unique identifier of the key.
              client_secret:
                type: string
                description: The client secret for the key.
              enabled:
                type: boolean
                description: Whether the key is enabled.
                examples:
                  - true
              created_at:
                type: string
                format: date-time
                description: The creation time of the key.
    ServiceAccountMeta:
      type: object
      description: Meta information for a service account
      properties:
        created_at:
          type: string
          format: date-time
          description: The creation time of the service account.
          examples:
            - '2023-01-15T10:30:00.000Z'
        updated_at:
          type: string
          format: date-time
          description: The last update time of the service account.
          examples:
            - '2023-02-20T14:45:00.000Z'
    ServiceAccountRelationships:
      type: object
      description: Relationships for a service account
      properties:
        groups:
          type: object
          required:
            - data
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/UserGroupRelationship'
        organisations:
          type: object
          required:
            - data
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/OrganisationRelationship'
    SchemeShareAttributes:
      type: object
      description: Attributes for a scheme share
      required:
        - permissions
        - read_only
      properties:
        permissions:
          type: array
          items:
            type: string
        read_only:
          type: boolean
          description: Indicates whether the scheme share is read-only
    SchemeShareRelationships:
      type: object
      required:
        - organisation_bridge
        - owner
        - shared_by
        - shared_with
        - scheme
      description: Relationships for a scheme share
      properties:
        organisation_bridge:
          type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/OrganisationBridgeRelationship'
        owner:
          type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/OrganisationRelationship'
        shared_by:
          type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/OrganisationRelationship'
        shared_with:
          type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/OrganisationRelationship'
        scheme:
          type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/SchemeRelationship'
    SchemeShareMeta:
      type: object
      description: Metadata for a scheme
      required:
        - start
        - end
      properties:
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
    TeamAttributes:
      type: object
      description: Attributes for a team
      properties:
        name:
          type: string
          description: The name of the team.
          examples:
            - Customer Service Representatives
        description:
          type: string
          description: A description of the team.
          examples:
            - >-
              Team responsible for handling customer inquiries and support
              requests
    TeamMeta:
      type: object
      description: Meta information for a team
      properties:
        created_at:
          type: string
          format: date-time
          description: The creation time of the team.
          examples:
            - '2025-07-16T12:42:40.000Z'
        updated_at:
          type: string
          format: date-time
          description: The last update time of the team.
          examples:
            - '2025-07-16T12:42:44.000Z'
    TeamRelationships:
      type: object
      description: Relationships for a team
      properties:
        members:
          type: object
          required:
            - data
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/UserRelationship'
        organisation:
          type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/OrganisationRelationship'
        schemas:
          type: object
          required:
            - data
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/FormSchemaRelationship'
    UserAttributes:
      type: object
      description: Attributes for a user
      properties:
        email:
          type: string
          format: email
          description: The email address of the user.
          examples:
            - john.doe@example.com
        status:
          type: string
          enum:
            - active
            - inactive
            - pending
            - unknown
          description: >
            The membership status of this user in the organisation in the
            request URL.

            Only populated on org-scoped member endpoints; absent on global user

            endpoints.
          examples:
            - active
        identities:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
                description: The unique identifier for the identity.
                examples:
                  - 39ce13b8-1116-416a-ad5f-3c5edfd44f53
              platform:
                type: string
                description: The platform of the identity.
                examples:
                  - multi_tenant
              meta:
                type:
                  - object
                  - 'null'
                additionalProperties: true
                description: Additional metadata for the identity.
        profile:
          type: object
          properties:
            work:
              type: object
              properties:
                occupation:
                  type: string
                  description: The occupation of the user.
                  examples:
                    - Site Manager
                cscs:
                  type: string
                  description: The CSCS card number of the user.
                  examples:
                    - CSC123456
                eusr:
                  type: string
                  description: The EUSR card number of the user.
                  examples:
                    - EUR789123
                start_date:
                  type: string
                  format: date
                  description: The start date of the user's employment.
                  examples:
                    - '2020-03-01T00:00:00.000Z'
            personal:
              type: object
              properties:
                first_name:
                  type: string
                  description: The first name of the user.
                  examples:
                    - John
                last_name:
                  type: string
                  description: The last name of the user.
                  examples:
                    - Doe
                dob:
                  type: string
                  format: date
                  description: The date of birth of the user.
                  examples:
                    - '1985-06-15T00:00:00.000Z'
                username:
                  type: string
                  description: The username of the user.
                  examples:
                    - johndoe
            contact:
              type: object
              properties:
                mobile:
                  type: string
                  description: The mobile number of the user.
                  examples:
                    - +44 7700 900123
                landline:
                  type: string
                  description: The landline of the user.
                  examples:
                    - +44 20 7946 0958
            address:
              type: object
              properties:
                number:
                  type: string
                  description: The house number of the user's address.
                  default: ''
                  examples:
                    - '42'
                street:
                  type: string
                  description: The street of the user's address.
                  examples:
                    - High Street
                area:
                  type: string
                  description: The area of the user's address.
                  examples:
                    - Westminster
                town:
                  type: string
                  description: The town of the user's address.
                  examples:
                    - London
                county:
                  type: string
                  description: The county of the user's address.
                  examples:
                    - Greater London
                postcode:
                  type: string
                  description: The postcode of the user's address.
                  examples:
                    - SW1A 1AA
                country_code:
                  type: string
                  description: The country code of the user's address.
                  examples:
                    - GB
                what3words:
                  type: string
                  description: The what3words location of the user's address.
                  examples:
                    - filled.count.soap
            settings:
              type: object
              properties:
                preferred_language:
                  type: string
                  description: The preferred language of the user.
                  default: en-GB
                  examples:
                    - en-GB
                timezone:
                  type: string
                  description: The timezone of the user.
                  examples:
                    - Europe/London
    UserMeta:
      type: object
      description: Metadata for a user
      properties:
        grants:
          type: array
          items:
            type: string
          description: >-
            This data is only returned on the whoami endpoint - it contains all
            of the user's granted permissions.
    UserRelationships:
      type: object
      description: Relationships for a user
      properties:
        organisations:
          type: object
          required:
            - data
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/OrganisationRelationship'
        teams:
          type: object
          required:
            - data
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/TeamRelationship'
        managing_organisation:
          type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/OrganisationRelationship'
    UserGroupRelationship:
      type: object
      description: Represents a relationship to a group
      required:
        - id
        - type
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the group
        type:
          type: string
          const: groups
    NomenclatureRelationship:
      type: object
      description: Represents a relationship to a nomenclature resource
      required:
        - id
        - type
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the nomenclature resource
        type:
          type: string
          const: nomenclature
    OrganisationBridgeRelationship:
      type: object
      description: Represents a relationship to an organisation bridge
      required:
        - id
        - type
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the organisation bridge
        type:
          type: string
          const: organisation-bridges
    SchemeRelationship:
      type: object
      description: Represents a relationship to a scheme
      required:
        - id
        - type
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the scheme
        type:
          type: string
          const: schemes
    FormSchemaRelationship:
      type: object
      description: Represents a relationship to a form schema
      required:
        - id
        - type
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the form schema
        type:
          type: string
          const: form-schemas
  securitySchemes:
    Session:
      description: |
        Session token for authentication.
      in: header
      name: X-Session-Token
      type: apiKey
    OAuth2:
      description: |
        OAuth2 token for authentication.
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://auth.ctrl-hub.com/oauth2/token
      type: oauth2
    Cookie:
      description: |
        Cookie token for authentication.
      in: cookie
      name: ctrl_hub_session
      type: apiKey

````