/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"