openapi: 3.0.4
info:
  title: Permissions-access-control-API
  description: "External API for managing role assignments in the Relativity Permissions\
    \ service.\r\n\r\nThis API allows you to:\r\n- **List** current role assignments\
    \ on a fileshare or instance (tenant) node.\r\n- **Assign** roles to groups on\
    \ a fileshare or instance node.\r\n- **Revoke** roles from groups on a fileshare\
    \ or instance node.\r\n\r\n**Authentication**: End user bearer tokens only.\r\n\
    \r\n**Authorization**: The authenticated user must hold the `secure` permission\
    \ on the target node and have view access to referenced groups.\r\n\r\n**Role\
    \ keys** follow the `r1_{product}_{role_name}` convention (e.g. `r1_staging_viewer`)."
  version: v1.0
servers:
- url: /Relativity.REST/api
  description: The URL prefix
paths:
  /access-control/public/v1/role-assignments/{nodeType}/{nodeKey}:
    get:
      tags:
      - Permissions Access Control
      summary: List role assignments on a node.
      parameters:
      - name: nodeType
        in: path
        description: The type of the node. Only 'fileshare' is supported.
        required: true
        schema:
          type: string
      - name: nodeKey
        in: path
        description: The key of the node.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RoleAssignment'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RoleAssignment'
            text/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RoleAssignment'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal Server Error
    post:
      tags:
      - Permissions Access Control
      summary: Batch assign and/or revoke roles on a node.
      parameters:
      - name: nodeType
        in: path
        description: The type of the node. Only 'fileshare' is supported.
        required: true
        schema:
          type: string
      - name: nodeKey
        in: path
        description: The key of the node.
        required: true
        schema:
          type: string
      requestBody:
        description: The role assignment/revocation request.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalBulkRoleAssignmentRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/ExternalBulkRoleAssignmentRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ExternalBulkRoleAssignmentRequest'
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal Server Error
  /access-control/public/v1/role-assignments/instance:
    get:
      tags:
      - Permissions Access Control
      summary: List role assignments on the instance (tenant) node.
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RoleAssignment'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RoleAssignment'
            text/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RoleAssignment'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal Server Error
    post:
      tags:
      - Permissions Access Control
      summary: Batch assign and/or revoke roles on the instance (tenant) node.
      requestBody:
        description: The role assignment/revocation request.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalBulkRoleAssignmentRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/ExternalBulkRoleAssignmentRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ExternalBulkRoleAssignmentRequest'
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal Server Error
components:
  schemas:
    ExternalBulkRoleAssignmentRequest:
      type: object
      properties:
        assign:
          type: array
          items:
            $ref: '#/components/schemas/ExternalRoleAssignmentPair'
          description: Role assignments to apply. Role keys must use the r1_ prefix.
          nullable: true
        revoke:
          type: array
          items:
            $ref: '#/components/schemas/ExternalRoleAssignmentPair'
          description: Role assignments to revoke. Role keys must use the r1_ prefix.
          nullable: true
      additionalProperties: false
      description: "Request to batch assign and/or revoke roles via the external API.\r\
        \nRole keys must use the r1_ prefix (e.g. r1_staging_viewer)."
    ExternalRoleAssignmentPair:
      required:
      - groupId
      - roleKey
      type: object
      properties:
        roleKey:
          minLength: 1
          type: string
          description: The role key with r1_ prefix (e.g. r1_staging_viewer).
        groupId:
          minLength: 1
          type: string
          description: The group identifier.
      additionalProperties: false
      description: A role and group pair used in external bulk operations.
    RoleAssignment:
      required:
      - groupId
      - roleKey
      type: object
      properties:
        roleKey:
          minLength: 1
          type: string
          description: The role key with r1_ prefix (e.g. r1_staging_viewer).
        groupId:
          minLength: 1
          type: string
          description: The group identifier.
      additionalProperties: false
      description: A single role assignment entry in the external API.
  securitySchemes:
    OAuth:
      type: http
      description: Standard Authorization header using the OAuth scheme. Paste in
        token without Bearer prefix.
      scheme: bearer
      bearerFormat: JWT
security:
- OAuth: []
tags:
- name: Permissions Access Control
  description: "External public API for managing role assignments.\r\nRole keys must\
    \ use the r1_ prefix (e.g. r1_staging_viewer).\r\nEnd user token is required"