Netcracker Roles API

openapi: 3.2.0
info:
  title: Netcracker Roles API
  version: '2026.1'
  contact:
    name: Netcracker Opensource Group
    email: opensourcegroup@netcracker.com
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  x-api-kind: BWC
  description: 'Operations tagged Roles across 2 of this provider''s published API definitions: netcracker-qubership-apihub-admin-openapi.yml, netcracker-qubership-apihub-registry-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{apihub}.qubership.org
  description: Primary APIHUB server endpoint (use the apihub variable to select production, development, or staging).
  variables:
    apihub:
      description: APIHUB subdomain/environment selector (apihub=production, dev.apihub=development, staging.apihub=staging).
      enum:
      - apihub
      - dev.apihub
      - staging.apihub
      default: apihub
security:
- BearerAuth: []
- CookieAuth: []
- api-key: []
- PersonalAccessToken: []
tags:
- name: Roles
  description: APIs for role management.
paths:
  /api/v2/roles:
    post:
      tags:
      - Roles
      summary: Create a new role
      description: 'Create a new role with the set of available permissions for this role.


        The role may be assigned to the user for the specific package.


        The "read content of public packages" permissions is applied for all roles by default (except the private packages with default role = **none**).

        '
      operationId: postRoles
      requestBody:
        description: Role creation parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoleCreate'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Role'
                - type: object
                  properties:
                    permissions:
                      type: array
                      description: List of permissions applicable to the role.
                      items:
                        $ref: '#/components/schemas/Permission'
                      example:
                      - read
                      - create_and_update_package
                      - delete_package
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
      - Roles
      summary: Get list of existing roles
      description: List of all roles and their permissions.
      operationId: getRoles
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  roles:
                    description: List of existing roles.
                    type: array
                    items:
                      allOf:
                      - $ref: '#/components/schemas/Role'
                      - type: object
                        properties:
                          readOnly:
                            description: 'A flag that indicates an immutability of a role. readOnly roles cannot be changed or deleted.

                              '
                            type: boolean
                            default: false
                          permissions:
                            type: array
                            description: List of permissions applicable to the role.
                            items:
                              $ref: '#/components/schemas/Permission_2'
                            example:
                            - read
                            - create_and_update_package
                            - delete_package
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
    servers:
    - url: https://{apihub}.qubership.org
      description: Primary APIHUB server endpoint (use the apihub variable to select production, development, or staging).
      variables:
        apihub:
          description: APIHUB subdomain/environment selector (apihub=production, dev.apihub=development, staging.apihub=staging).
          enum:
          - apihub
          - dev.apihub
          - staging.apihub
          default: apihub
  /api/v2/roles/{roleId}:
    parameters:
    - name: roleId
      in: path
      required: true
      description: Unique role identifier (slug). Lowercase letters, digits, and hyphens are expected; value is immutable for an existing role.
      schema:
        type: string
        pattern: ^[a-z0-9-]
        example: editor
    patch:
      tags:
      - Roles
      summary: Update role
      description: 'Update role parameters.


        If a parameter is not provided in the request, its value remains unchanged.


        Read-only roles cannot be updated.

        '
      operationId: patchRolesId
      requestBody:
        description: Role update payload. Omitted fields are left unchanged; provided permissions replace the current permission list.
        content:
          application/json:
            schema:
              type: object
              required:
              - permissions
              properties:
                permissions:
                  description: 'List of role permissions.

                    Current role permissions will be replaced by the transmitted list.

                    '
                  type: array
                  items:
                    $ref: '#/components/schemas/Permission'
                  example:
                  - read
                  - create_and_update_package
                  - delete_package
      responses:
        '204':
          description: No content
          content: {}
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
    delete:
      tags:
      - Roles
      summary: Delete role
      description: 'Permanently delete a role and its permission assignment.


        When a role is deleted, users that had this role are removed from package membership lists where it was assigned.


        Roles with **readOnly:true** cannot be deleted.

        '
      operationId: deleteRolesId
      responses:
        '204':
          description: No content
          content: {}
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
    servers:
    - url: https://{apihub}.qubership.org
      description: Primary APIHUB server endpoint (use the apihub variable to select production, development, or staging).
      variables:
        apihub:
          description: APIHUB subdomain/environment selector (apihub=production, dev.apihub=development, staging.apihub=staging).
          enum:
          - apihub
          - dev.apihub
          - staging.apihub
          default: apihub
  /api/v2/roles/changeOrder:
    post:
      tags:
      - Roles
      summary: Update the roles order
      description: 'Replace the global role display/order configuration with the submitted ordered list.


        The request must contain each existing role exactly once; missing or duplicate role IDs cause a 400 error. The change is applied atomically.

        '
      operationId: postRolesChangeOrder
      requestBody:
        description: Ordered list of role IDs representing the complete desired role order.
        content:
          application/json:
            schema:
              type: object
              description: Payload containing the complete ordered role list. Order is significant and all existing roles must be present exactly once.
              required:
              - roles
              properties:
                roles:
                  type: array
                  items:
                    type: string
                  example:
                  - admin
                  - owner
                  - editor
                  - viewer
                  - none
      responses:
        '204':
          description: No content
          content: {}
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://{apihub}.qubership.org
      description: Primary APIHUB server endpoint (use the apihub variable to select production, development, or staging).
      variables:
        apihub:
          description: APIHUB subdomain/environment selector (apihub=production, dev.apihub=development, staging.apihub=staging).
          enum:
          - apihub
          - dev.apihub
          - staging.apihub
          default: apihub
  /api/v2/admins:
    get:
      x-nc-api-audience: noBWC
      tags:
      - Roles
      summary: Get list of system administrators
      description: Retrieve all users currently configured as system administrators.
      operationId: getAdmins
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  admins:
                    description: List of system administrators.
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
    post:
      x-nc-api-audience: noBWC
      tags:
      - Roles
      summary: Add a system administrator
      description: 'Add an existing user as a system administrator.

        '
      operationId: postAdmins
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - userId
              properties:
                userId:
                  description: User login (username), for example user1221.
                  type: string
                  example: user1221
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  admins:
                    description: List of system administrators.
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                IncorrectInputParams:
                  $ref: '#/components/examples/IncorrectInputParameters'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
    servers:
    - url: https://{apihub}.qubership.org
      description: Primary APIHUB server endpoint (use the apihub variable to select production, development, or staging).
      variables:
        apihub:
          description: APIHUB subdomain/environment selector (apihub=production, dev.apihub=development, staging.apihub=staging).
          enum:
          - apihub
          - dev.apihub
          - staging.apihub
          default: apihub
  /api/v2/admins/{userId}:
    delete:
      x-nc-api-audience: noBWC
      tags:
      - Roles
      summary: Delete system administrator
      description: Delete a user from the system administrators group.
      operationId: deleteAdminsId
      parameters:
      - name: userId
        description: User login (username), for example user1221.
        in: path
        required: true
        schema:
          type: string
          example: user1221
      responses:
        '204':
          description: No content
          content: {}
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
    servers:
    - url: https://{apihub}.qubership.org
      description: Primary APIHUB server endpoint (use the apihub variable to select production, development, or staging).
      variables:
        apihub:
          description: APIHUB subdomain/environment selector (apihub=production, dev.apihub=development, staging.apihub=staging).
          enum:
          - apihub
          - dev.apihub
          - staging.apihub
          default: apihub
  /api/v2/permissions:
    get:
      tags:
      - Roles
      summary: Get list of permissions
      description: List of all permissions.
      operationId: getPermissions
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  permissions:
                    description: List of available permissions.
                    type: array
                    items:
                      type: object
                      properties:
                        permission:
                          $ref: '#/components/schemas/Permission_2'
                        name:
                          type: string
                          description: Name of the permission
                          example: Read content of public package
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://{apihub}.qubership.org
      description: Primary APIHUB server endpoint (use the apihub variable to select production, development, or staging).
      variables:
        apihub:
          description: APIHUB subdomain/environment selector (apihub=production, dev.apihub=development, staging.apihub=staging).
          enum:
          - apihub
          - dev.apihub
          - staging.apihub
          default: apihub
  /api/v2/packages/{packageId}/availableRoles:
    parameters:
    - $ref: '#/components/parameters/packageId'
    get:
      tags:
      - Roles
      summary: Get list of available roles for package
      description: 'List of available roles to change for package and current user (by access token).

        '
      operationId: getPackagesIdAvailableRoles
      parameters:
      - name: id
        in: query
        description: Unique user login (username) used to authenticate the user.
        required: false
        schema:
          type: string
          example: user1221
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: List of available roles.
                properties:
                  roles:
                    description: List of available roles.
                    type: array
                    items:
                      allOf:
                      - $ref: '#/components/schemas/Role'
                      - type: object
                        properties:
                          readOnly:
                            description: 'A flag that indicates an immutability of a role. readOnly roles cannot be changed or deleted.

                              '
                            type: boolean
                            default: false
                          permissions:
                            type: array
                            description: List of permissions applicable to the role.
                            items:
                              $ref: '#/components/schemas/Permission_2'
                            example:
                            - read
                            - create_and_update_package
                            - delete_package
        '301':
          description: Moved Permanently
          headers:
            Location:
              schema:
                type: string
              description: Current ednpoint with new packageId of moved package
            X-New-Package-Id:
              schema:
                type: string
              description: New packageId of moved package
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                PackageNotFound:
                  $ref: '#/components/examples/PackageNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
    servers:
    - url: https://{apihub}.qubership.org
      description: Primary APIHUB server endpoint (use the apihub variable to select production, development, or staging).
      variables:
        apihub:
          description: APIHUB subdomain/environment selector (apihub=production, dev.apihub=development, staging.apihub=staging).
          enum:
          - apihub
          - dev.apihub
          - staging.apihub
          default: apihub
  /api/v2/packages/{packageId}/members:
    parameters:
    - $ref: '#/components/parameters/packageId'
    post:
      tags:
      - Roles
      summary: Add members to the package
      description: 'Add new user (one user or multiple users) with a role to the package.

        A member may be added to the package if the assigned role is greater than the existing one.

        '
      operationId: postPackagesIdMembers
      requestBody:
        description: Package members assignment parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MemberCreate'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  members:
                    description: List of the package's users with roles
                    type: array
                    items:
                      $ref: '#/components/schemas/Member'
        '301':
          description: Moved Permanently
          headers:
            Location:
              schema:
                type: string
              description: Current ednpoint with new packageId of moved package
            X-New-Package-Id:
              schema:
                type: string
              description: New packageId of moved package
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                IncorrectInputParams:
                  $ref: '#/components/examples/IncorrectInputParameters'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                PackageNotFound:
                  $ref: '#/components/examples/PackageNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
    get:
      tags:
      - Roles
      summary: Get the package's members list
      description: List of all users and their roles, assigned to the particular package
      operationId: getPackagesIdMembers
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  members:
                    description: List of the package's users with roles
                    type: array
                    items:
                      $ref: '#/components/schemas/Member'
        '301':
          description: Moved Permanently
          headers:
            Location:
              schema:
                type: string
              description: Current ednpoint with new packageId of moved package
            X-New-Package-Id:
              schema:
                type: string
              description: New packageId of moved package
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                PackageNotFound:
                  $ref: '#/components/examples/PackageNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
    servers:
    - url: https://{apihub}.qubership.org
      description: Primary APIHUB server endpoint (use the apihub variable to select production, development, or staging).
      variables:
        apihub:
          description: APIHUB subdomain/environment selector (apihub=production, dev.apihub=development, staging.apihub=staging).
          enum:
          - apihub
          - dev.apihub
          - staging.apihub
          default: apihub
  /api/v2/packages/{packageId}/members/{userId}:
    parameters:
    - $ref: '#/components/parameters/packageId'
    - name: userId
      in: path
      required: true
      description: Login of the user
      schema:
        type: string
        example: user1221
    patch:
      tags:
      - Roles
      summary: Package member update
      description: 'Change the member parameters on the package

        '
      operationId: patchPackagesIdMembersId
      requestBody:
        description: Package member update parameters
        content:
          application/json:
            schema:
              type: object
              required:
              - roleId
              - action
              properties:
                roleId:
                  type: string
                  description: Unique role identifier. The value is the slug of role name.
                  example: editor
                action:
                  type: string
                  description: Name of the action with user role.
                  enum:
                  - add
                  - remove
      responses:
        '204':
          description: No content
          content: {}
        '301':
          description: Moved Permanently
          headers:
            Location:
              schema:
                type: string
              description: Current ednpoint with new packageId of moved package
            X-New-Package-Id:
              schema:
                type: string
              description: New packageId of moved package
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                IncorrectInputParams:
                  $ref: '#/components/examples/IncorrectInputParameters'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                PackageNotFound:
                  $ref: '#/components/examples/PackageNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
    delete:
      tags:
      - Roles
      summary: Package member delete
      description: 'Delete (unassign) the member from the package. Response variants logic:

        * 200 - if the user has direct role assigned to the current package AND assignment to the parent package, will be returned his inherited role.

        * 204 - if the user has only direct role assigned to the current package, this assignment will be deleted.

        '
      operationId: deletePackagesIdMembersId
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  member:
                    $ref: '#/components/schemas/Member'
        '204':
          description: No content
          content: {}
        '301':
          description: Moved Permanently
          headers:
            Location:
              schema:
                type: string
              description: Current ednpoint with new packageId of moved package
            X-New-Package-Id:
              schema:
                type: string
              description: New packageId of moved package
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples: {}
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples: {}
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/sc

# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/netcracker/refs/heads/main/openapi/netcracker-roles-api-openapi.yml