snapshot of https://github.com/mattermost/mattermost.git (master, 2026-09-16; blobs > 131072B omitted)

api/v4/source/access_control.yaml

@@ -0,0 +1,718 @@
+  /api/v4/access_control_policies:
+    put:
+      tags:
+        - access control
+      summary: Create an access control policy
+      description: |
+        Creates a new access control policy.
+        ##### Permissions
+        Must have the `manage_system` permission.
+      operationId: CreateAccessControlPolicy
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AccessControlPolicy"
+      responses:
+        "200":
+          description: Access control policy created successfully.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AccessControlPolicy"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  /api/v4/access_control_policies/cel/check:
+    post:
+      tags:
+        - access control
+      summary: Check an access control policy expression
+      description: |
+        Checks the syntax and validity of an access control policy expression.
+        ##### Permissions
+        Must have the `manage_system` permission.
+      operationId: CheckAccessControlPolicyExpression
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                expression:
+                  type: string
+                  description: The expression to check.
+      responses:
+        "200":
+          description: Expression check result.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/ExpressionError"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  /api/v4/access_control_policies/cel/validate_requester:
+    post:
+      tags:
+        - access control
+      summary: Validate if the current user matches a CEL expression
+      description: |
+        Validates whether the current authenticated user matches the given CEL expression.
+        This is used to determine if a channel admin can test expressions they match.
+        ##### Permissions
+        Must have `manage_system` permission OR be a channel admin for the specified channel (channelId required for channel admins).
+      operationId: ValidateExpressionAgainstRequester
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                expression:
+                  type: string
+                  description: The CEL expression to validate against the current user.
+                channelId:
+                  type: string
+                  description: The channel ID for channel-specific permission checks (required for channel admins).
+              required:
+                - expression
+      responses:
+        "200":
+          description: Validation result returned successfully.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  requester_matches:
+                    type: boolean
+                    description: Whether the current user matches the expression.
+                required:
+                  - requester_matches
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  /api/v4/access_control_policies/cel/test:
+    post:
+      tags:
+        - access control
+      summary: Test an access control policy expression
+      description: |
+        Tests an access control policy expression against users to see who would be affected.
+        ##### Permissions
+        Must have the `manage_system` permission.
+      operationId: TestAccessControlPolicyExpression
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/QueryExpressionParams"
+      responses:
+        "200":
+          description: Expression test result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AccessControlPolicyTestResponse"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  /api/v4/access_control_policies/cel/simulate_users:
+    post:
+      tags:
+        - access control
+      summary: Simulate an access control policy decision for an explicit user list
+      description: |
+        Runs the dual-lane PDP simulation against a draft (unsaved) access
+        control policy for an explicit set of users (with optional per-user
+        session-attribute overrides). The server compiles the draft
+        in-memory, layers on persisted higher-scoped permission policies,
+        and returns per-user, per-action ALLOW/DENY decisions plus blame
+        attribution for any deny.
+
+        Backs the picker-driven "Simulate access" UX in the System Console
+        and Channel Settings so authors can see how a draft interacts with
+        persisted higher-scoped policies before saving.
+
+        Gated by the `PermissionPolicies` feature flag and the Enterprise
+        Advanced license. Returns 501 (Not Implemented) when either is
+        missing.
+
+        ##### Permissions
+        Must have the `manage_system` permission, OR be a team admin with
+        `manage_team_access_rules` on the request's `team_id` (when any
+        provided `channel_id` resolves to a channel in that team), OR be a
+        channel admin with `manage_channel_access_rules` on the request's
+        `channel_id`.
+      operationId: SimulateAccessControlPolicyForUsers
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PolicySimulationByUsersParams"
+      responses:
+        "200":
+          description: Per-user, per-action simulation results.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PolicySimulationResponse"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  /api/v4/access_control_policies/search:
+    post:
+      tags:
+        - access control
+      summary: Search access control policies
+      description: |
+        Searches for access control policies based on given criteria.
+        ##### Permissions
+        Must have the `manage_system` permission.
+      operationId: SearchAccessControlPolicies
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AccessControlPolicySearch"
+      responses:
+        "200":
+          description: Search results for access control policies.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AccessControlPoliciesWithCount"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  /api/v4/access_control_policies/cel/autocomplete/fields:
+    get:
+      tags:
+        - access control
+      summary: Get autocomplete fields for access control policies
+      description: |
+        Provides a list of fields that can be used for autocompletion when creating/editing access control policy expressions.
+        ##### Permissions
+        Must have the `manage_system` permission.
+      operationId: GetAccessControlPolicyAutocompleteFields
+      parameters:
+        - name: after
+          in: query
+          description: The field ID to start after for pagination.
+          required: false
+          schema:
+            type: string
+        - name: limit
+          in: query
+          description: The maximum number of fields to return.
+          required: true
+          schema:
+            type: integer
+            default: 60
+      responses:
+        "200":
+          description: Autocomplete fields retrieved successfully.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AccessControlFieldsAutocompleteResponse"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  "/api/v4/access_control_policies/{policy_id}":
+    get:
+      tags:
+        - access control
+      summary: Get an access control policy
+      description: |
+        Gets a specific access control policy by its ID.
+        ##### Permissions
+        Must have the `manage_system` permission.
+      operationId: GetAccessControlPolicy
+      parameters:
+      - name: policy_id
+        in: path
+        description: The ID of the access control policy.
+        required: true
+        schema:
+          type: string
+      responses:
+        "200":
+          description: Access control policy retrieved successfully.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AccessControlPolicy"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+    delete:
+      tags:
+        - access control
+      summary: Delete an access control policy
+      description: |
+        Deletes an access control policy by its ID.
+        ##### Permissions
+        Must have the `manage_system` permission.
+      operationId: DeleteAccessControlPolicy
+      parameters:
+      - name: policy_id
+        in: path
+        description: The ID of the access control policy.
+        required: true
+        schema:
+          type: string
+      responses:
+        "200":
+          description: Access control policy deleted successfully.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  "/api/v4/access_control_policies/{policy_id}/activate":
+    get:
+      deprecated: true
+      tags:
+        - access control
+      summary: Activate or deactivate an access control policy
+      description: |
+        Updates the active status of an access control policy.
+
+        **Deprecated:** This endpoint will be removed in a future release. Use the dedicated access control policy update endpoint instead.
+        Link: </api/v4/access_control_policies/activate>; rel="successor-version"
+
+        ##### Permissions
+        Must have the `manage_system` permission.
+      operationId: UpdateAccessControlPolicyActiveStatus
+      parameters:
+      - name: policy_id
+        in: path
+        description: The ID of the access control policy.
+        required: true
+        schema:
+          type: string
+      - name: active
+        in: query
+        description: Set to "true" to activate, "false" to deactivate.
+        required: true
+        schema:
+          type: boolean
+      responses:
+        "200":
+          description: Policy active status updated successfully.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  "/api/v4/access_control_policies/{policy_id}/assign":
+    post:
+      tags:
+        - access control
+      summary: Assign an access control policy to channels or teams
+      description: |
+        Assigns an access control policy to a list of channels and/or teams.
+        ##### Permissions
+        Must have the `manage_system` permission.
+      operationId: AssignAccessControlPolicyToChannels
+      parameters:
+      - name: policy_id
+        in: path
+        description: The ID of the access control policy.
+        required: true
+        schema:
+          type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                channel_ids:
+                  type: array
+                  items:
+                    type: string
+                  description: The IDs of the channels to assign the policy to.
+                team_ids:
+                  type: array
+                  items:
+                    type: string
+                  description: >
+                    The IDs of the teams to assign the policy to. Requires the
+                    `manage_system` permission. Any unknown team ID is rejected
+                    with a 400.
+      responses:
+        "200":
+          description: Policy assigned to the channels and/or teams successfully.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  "/api/v4/access_control_policies/{policy_id}/unassign":
+    delete:
+      tags:
+        - access control
+      summary: Unassign an access control policy from channels or teams
+      description: |
+        Unassigns an access control policy from a list of channels and/or teams.
+        ##### Permissions
+        Must have the `manage_system` permission.
+      operationId: UnassignAccessControlPolicyFromChannels
+      parameters:
+      - name: policy_id
+        in: path
+        description: The ID of the access control policy.
+        required: true
+        schema:
+          type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                channel_ids:
+                  type: array
+                  items:
+                    type: string
+                  description: The IDs of the channels to unassign the policy from.
+                team_ids:
+                  type: array
+                  items:
+                    type: string
+                  description: >
+                    The IDs of the teams to unassign the policy from. Requires the
+                    `manage_system` permission. Any unknown team ID is rejected
+                    with a 400.
+      responses:
+        "200":
+          description: Policy unassigned from the channels and/or teams successfully.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  "/api/v4/access_control_policies/{policy_id}/resources/channels":
+    get:
+      tags:
+        - access control
+      summary: Get channels for an access control policy
+      description: |
+        Retrieves a paginated list of channels to which a specific access control policy is applied.
+        ##### Permissions
+        Must have the `manage_system` permission.
+      operationId: GetChannelsForAccessControlPolicy
+      parameters:
+      - name: policy_id
+        in: path
+        description: The ID of the access control policy.
+        required: true
+        schema:
+          type: string
+      - name: after
+        in: query
+        description: The channel ID to start after for pagination.
+        required: false
+        schema:
+          type: string
+      - name: limit
+        in: query
+        description: The maximum number of channels to return.
+        required: true
+        schema:
+          type: integer
+          default: 60
+      responses:
+        "200":
+          description: Channels retrieved successfully.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ChannelsWithCount"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  "/api/v4/access_control_policies/{policy_id}/resources/channels/search":
+    post:
+      tags:
+        - access control
+      summary: Search channels for an access control policy
+      description: |
+        Searches for channels associated with a specific access control policy based on search criteria.
+        ##### Permissions
+        Must have the `manage_system` permission.
+      operationId: SearchChannelsForAccessControlPolicy
+      parameters:
+      - name: policy_id
+        in: path
+        description: The ID of the access control policy.
+        required: true
+        schema:
+          type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ChannelSearch"
+      responses:
+        "200":
+          description: Channel search results retrieved successfully.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ChannelsWithCount"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  "/api/v4/channels/{channel_id}/access_control/attributes":
+    get:
+      tags:
+        - access control
+        - channels
+      summary: Get access control attributes for a channel
+      description: |
+        Retrieves the effective access control policy attributes for a specific channel.
+        This can be used to understand what attributes are currently being applied to the channel by the access control system.
+        ##### Permissions
+        Must have `read_channel` permission for the specified channel.
+      operationId: GetChannelAccessControlAttributes
+      parameters:
+        - name: channel_id
+          in: path
+          description: The ID of the channel.
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Access control attributes retrieved successfully.
+          content:
+            application/json:
+              schema:
+                type: object # Placeholder - define more specifically if the structure is known
+                additionalProperties: true
+                description: A map of attribute names to their values as applied to the channel.
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  /api/v4/access_control_policies/cel/visual_ast:
+    post:
+      tags:
+        - access control
+      summary: Get the visual AST for a CEL expression
+      description: |
+        Retrieves the visual AST for a CEL expression.
+        ##### Permissions
+        Must have the `manage_system` permission.
+      operationId: GetCELVisualAST
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CELExpression"
+      responses:
+        "200":
+          description: Visual AST retrieved successfully.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/VisualExpression" 
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  /api/v4/access_control_policies/activate:
+    put:
+      tags:
+        - access control
+      summary: Activate or deactivate access control policies
+      description: |
+        Updates the active status of access control policies.
+
+        ##### Permissions
+        Must have the `manage_system` permission. OR be a channel admin with manage_channel_access_rules permission for the specified channels.
+      operationId: UpdateAccessControlPoliciesActive
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AccessControlPolicyActiveUpdateRequest"
+      responses:
+        "200":
+          description: Access control policies active status updated successfully.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AccessControlPolicy"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+  /api/v4/access_control/decisions/actions/search:
+    post:
+      tags:
+        - access control
+      summary: Search allowed actions for the current user (render-time decision)
+      description: |
+        Returns non-authoritative, render-time ABAC decisions for the current
+        session user on a given resource and set of actions. Use these decisions
+        to decide whether to show or hide UI controls before the user attempts
+        an action.
+
+        The subject is always the authenticated session user; there is no way to
+        probe another user's decisions. Server-side enforcement always re-evaluates
+        the full policy on the actual request and remains the source of truth.
+
+        Gated by the `PermissionPolicies` feature flag and an Enterprise license.
+        When ABAC is inactive for the resource, every action is returned as
+        `allowed: true, evaluated: true`.
+
+        ##### Permissions
+        Must be authenticated (any logged-in user).
+      operationId: SearchAccessControlDecisionActions
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ActionSearchRequest"
+      responses:
+        "200":
+          description: Render-time action decisions returned successfully.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ActionSearchResponse"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "500":
+          $ref: "#/components/responses/InternalServerError"