openapi: 3.1.0
info:
  title: Red Hat Ansible Automation Platform Add-Ons Roles API
  description: The Red Hat Ansible Automation Platform API provides programmatic access to the automation controller for managing IT infrastructure automation. It supports creating and launching job templates, managing inventories, tracking job execution status, and configuring credentials for connecting to managed hosts and external services.
  version: '2.6'
  contact:
    name: Red Hat Support
    url: https://access.redhat.com/support
  termsOfService: https://www.redhat.com/en/about/terms-use
servers:
- url: https://ansible-platform.example.com
  description: Ansible Automation Platform Server
security:
- bearerAuth: []
tags:
- name: Roles
  description: Operations for managing realm-level and client-level roles for authorization.
paths:
  /admin/realms/{realm}/roles:
    get:
      operationId: listRealmRoles
      summary: Red Hat List Realm Roles
      description: Retrieves the list of realm-level roles that can be assigned to users and groups.
      tags:
      - Roles
      parameters:
      - $ref: '#/components/parameters/RealmParam'
      - name: first
        in: query
        description: Pagination offset.
        schema:
          type: integer
        example: 10
      - name: max
        in: query
        description: Maximum number of results.
        schema:
          type: integer
        example: 10
      responses:
        '200':
          description: Successfully retrieved roles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Role'
              examples:
                Listrealmroles200Example:
                  summary: Default listRealmRoles 200 response
                  x-microcks-default: true
                  value:
                  - id: abc123
                    name: Example Title
                    description: A sample description.
                    composite: true
                    clientRole: true
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createRealmRole
      summary: Red Hat Create a Realm Role
      description: Creates a new realm-level role.
      tags:
      - Roles
      parameters:
      - $ref: '#/components/parameters/RealmParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Role'
            examples:
              CreaterealmroleRequestExample:
                summary: Default createRealmRole request
                x-microcks-default: true
                value:
                  id: abc123
                  name: Example Title
                  description: A sample description.
                  composite: true
                  clientRole: true
      responses:
        '201':
          description: Role created successfully
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          description: A role with the same name already exists.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Role:
      type: object
      description: A role that can be assigned to users or groups for authorization.
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the role.
          example: abc123
        name:
          type: string
          description: The name of the role.
          example: Example Title
        description:
          type: string
          description: A description of the role.
          example: A sample description.
        composite:
          type: boolean
          description: Whether this is a composite role containing other roles.
          example: true
        clientRole:
          type: boolean
          description: Whether this is a client-level role.
          example: true
  responses:
    UnauthorizedError:
      description: Authentication credentials are missing or invalid.
  parameters:
    RealmParam:
      name: realm
      in: path
      required: true
      description: The name of the Keycloak realm.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 Bearer token for authenticating API requests to the automation controller.
externalDocs:
  description: Ansible Automation Platform API Documentation
  url: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html-single/automation_execution_api_overview/index