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

# List roles

> Retrieve a list of roles



## OpenAPI

````yaml /api-reference/openapi.yaml get /v3/roles
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/roles:
    get:
      tags:
        - IAM Roles
      description: Retrieve a list of roles
      operationId: ListRoles
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          $ref: '#/components/responses/ListRoles'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorised'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - Session: []
        - Cookie: []
        - OAuth2: []
components:
  parameters:
    limit:
      name: limit
      in: query
      description: Limit the number of resources returned by the API
      required: false
      schema:
        type: integer
        format: int64
        minimum: 1
        default: 100
    offset:
      name: offset
      in: query
      description: Offset the resources returned by the API
      required: false
      schema:
        type: integer
        format: int64
        minimum: 0
        default: 0
  responses:
    ListRoles:
      description: Get a list of roles
      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:
                    title: A list of roles
                    type: array
                    items:
                      $ref: '#/components/schemas/Role'
              - $ref: '#/components/schemas/DocumentMeta'
              - $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
    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:
    Role:
      type: object
      description: A role
      required:
        - id
        - type
        - attributes
      properties:
        id:
          type: string
          description: The role identifier (e.g., scheme.owner)
        type:
          type: string
          const: roles
        attributes:
          $ref: '#/components/schemas/RoleAttributes'
        relationships:
          $ref: '#/components/schemas/RoleRelationships'
    DocumentMeta:
      type: object
      description: Document level meta about the resources on the server in list endpoints.
      required:
        - meta
      properties:
        meta:
          type: object
          required:
            - pagination
          properties:
            features:
              $ref: '#/components/schemas/Features'
            pagination:
              $ref: '#/components/schemas/Pagination'
    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
    RoleAttributes:
      type: object
      description: Attributes for a role
      required:
        - domain
        - role
        - name
        - description
        - available_scopes
      properties:
        domain:
          type: string
          description: The domain this role applies to
          examples:
            - projects
        role:
          type: string
          description: The role within the domain
          examples:
            - admin
        name:
          type: string
          description: Display name of the role
          examples:
            - Project admin
        description:
          type: string
          description: Human readable explanation of the role
          examples:
            - Full management of projects
        available_scopes:
          type: object
          description: Available scopes that can be applied when granting this role
          required:
            - attributes
            - patterns
          properties:
            attributes:
              type: array
              description: Attribute-based scope options
              items:
                type: object
                required:
                  - name
                  - type
                  - operations
                properties:
                  name:
                    type: string
                    description: The attribute name
                    examples:
                      - id
                      - author
                      - folder
                  type:
                    type: string
                    description: The attribute data type
                    enum:
                      - uuid
                      - string
                      - label
                      - number
                      - boolean
                  operations:
                    type: array
                    description: Supported comparison operations
                    items:
                      type: string
                      enum:
                        - '='
                        - '!='
                  resource_type:
                    type: string
                    description: >-
                      The resource type that this attribute applies to, relevant
                      when type is uuid. This can be used to fetch resources
                      from the API in order to get the UUIDs to supply as a
                      value
                    example:
                      - folders
                      - users
            patterns:
              type: array
              description: Pattern-based scope options
              items:
                type: object
                required:
                  - type
                  - field
                  - operations
                properties:
                  type:
                    type: string
                    description: The pattern type
                    enum:
                      - contains
                      - prefix
                      - suffix
                  field:
                    type: string
                    description: The field the pattern applies to
                    examples:
                      - name
                  operations:
                    type: array
                    description: Supported comparison operations
                    items:
                      type: string
                      enum:
                        - '='
                        - '!='
                        - '~'
    RoleRelationships:
      type: object
      description: Relationships for a role
      properties:
        permissions:
          type: object
          required:
            - data
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/PermissionRelationship'
    Features:
      type: object
      description: Represents feature configurations of the API
      properties:
        include:
          type: object
          properties:
            options:
              type: array
              items:
                type: string
                examples:
                  - related.resource
    Pagination:
      type: object
      description: Represents pagination details for API responses
      required:
        - counts
        - current_page
        - offsets
        - requested
      properties:
        counts:
          type: object
          required:
            - pages
            - resources
          properties:
            pages:
              type: integer
              examples:
                - 1
            resources:
              type: integer
              examples:
                - 1
        current_page:
          type: integer
          examples:
            - 1
        offsets:
          type: object
          required:
            - next
            - previous
          properties:
            next:
              type:
                - integer
                - 'null'
              examples:
                - null
            previous:
              type:
                - integer
                - 'null'
              examples:
                - null
        requested:
          type: object
          required:
            - limit
            - offset
          properties:
            limit:
              type: integer
              examples:
                - 10
            offset:
              type: integer
              examples:
                - 0
    PermissionRelationship:
      type: object
      description: Represents a relationship to a permission
      required:
        - id
        - type
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the permission
        type:
          type: string
          const: permissions
  securitySchemes:
    Session:
      description: |
        Session token for authentication.
      in: header
      name: X-Session-Token
      type: apiKey
    Cookie:
      description: |
        Cookie token for authentication.
      in: cookie
      name: ctrl_hub_session
      type: apiKey
    OAuth2:
      description: |
        OAuth2 token for authentication.
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://auth.ctrl-hub.com/oauth2/token
      type: oauth2

````