openapi: 3.0.1
info:
  title: Roles API
  description: Provides access to the roles in Hyperproof.
  version: '1.0'
servers:
  - url: https://api.hyperproof.app/v1/roles
    description: Hyperproof US
  - url: https://api.hyperproofgov.app/v1/roles
    description: Hyperproof Gov
  - url: https://api.hyperproof.eu/v1/roles
    description: Hyperproof EU
security:
  - oauth2: []
paths:
  /:
    get:
      summary: Get Roles
      description: >
        `GET /`


        #### Description


        Retrieves a list of all Hyperproof roles, including role names,
        descriptions, and associated permissions.
      operationId: get-roles
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleCollection'
              example:
                - id: f5a110d4-00a2-11ee-acbd-2bbf74beda27
                  name: Control Contributor
                  scope: control
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://accounts.hyperproof.app/oauth/token
          scopes:
            user.read: Grants read access to the roles
  schemas:
    Role:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier for the role.
        name:
          type: string
          description: The name of the role.
        scope:
          type: string
          description: The type of object that this role can be applied to.
      example:
        id: f5a110d4-00a2-11ee-acbd-2bbf74beda27
        name: Control Contributor
        scope: control
    RoleCollection:
      type: array
      description: A collection of roles.
      items:
        $ref: '#/components/schemas/Role'
