Red Hat Roles API

openapi: 3.2.0
info:
  title: Red Hat Build of Keycloak Admin REST Roles API
  description: The Red Hat Build of Keycloak Admin REST API provides programmatic access to manage identity and access management functions, including realm configuration, user management, client registration, role assignments, identity provider configuration, and session management. It serves as the administrative interface for the Red Hat build of Keycloak identity platform.
  version: '26.0'
  contact:
    name: Red Hat Support
    url: https://access.redhat.com/support
  termsOfService: https://www.redhat.com/en/about/terms-use
servers:
- url: https://keycloak.example.com
  description: Keycloak 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:
  parameters:
    RealmParam:
      name: realm
      in: path
      required: true
      description: The name of the Keycloak realm.
      schema:
        type: string
  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.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Access token obtained via direct access grant or authorization code flow from the Keycloak master realm or configured realm.
externalDocs:
  description: Red Hat Build of Keycloak Admin REST API Documentation
  url: https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0/html/server_developer_guide/admin_rest_api