> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opal.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure reviewers

> Learn how to configure required reviewers for access requests.

All resources and groups in Opal can be requestable with configurable approval options and reviewers. Use this guide to learn how admins can configure the reviewers of access requests.

## Owners

Owners are users who can be:

* **Reviewers**: Users who can review and approve access requests
* **Admins**: Users who can manage the full configuration of policies for resources and groups

You can manage owners from the **Inventory** > **Owners** tab. There, you can find the following settings for reviewers:

1. **Reviewer Escalation Policy:**

* **Notify everyone**: As the default option, Opal notifies all required reviewers at once. Opal requires just one approval from all required reviewers to complete the request.
* **Reviewer escalation policy**: Once configured, Opal creates an explicit escalation order. In this example, Opal notifies the first reviewer. After the escalation time has passed, Opal notifies the next reviewer, and so on.

2. **Linked reviewer channel:** A Slack or [Microsoft Teams](https://docs.opal.dev/integrations/microsoft-teams.md#reviewer-channels) channel that receives a message for every access request.

3. **Source group:** Opal keeps the user list for this owner synchronized with a group of your choice. You can still edit the escalation path in the Users tab, but you can't add or remove users from this owner directly.

![2262](https://mintcdn.com/opalsecurity/lwwIeFbsleftxaXx/images/docs/c30d98ca7d1deab35cef4945a47293f0c32c62d8ac2a1d68ef933483065b6c23-edit-api-owner.png?fit=max\&auto=format\&n=lwwIeFbsleftxaXx\&q=85\&s=7f68708e35ce4c016cb5933e7d540da3)

### Empty owner notifications

Access reviews that require owner approval will fail when owner groups are empty. To receive [notifications](https://docs.opal.dev/docs/notifications.md) about empty owner groups, enable **Error notification setting** in **Configuration** > **Organization Settings** > **Advanced**.

## Approval workflows

For resources and groups, the **Request Configuration** section gives admins an overview of the approval logic. You can create multiple request configurations if you want to apply different approval logic for different requesting users, groups, or roles.

![2262](https://mintcdn.com/opalsecurity/fu-nWazMe1LxLhxi/images/docs/32cb76c-reqconfig.png?fit=max\&auto=format\&n=fu-nWazMe1LxLhxi\&q=85\&s=33e65e47301c10fad4e31280a0fc5715)

### Priority and fallback

When a user requests access, Opal selects **one** request configuration for that request:

1. Evaluate conditional configurations in ascending priority order (`1`, then `2`, then `3`, …). The first configuration whose condition matches the request wins. A condition can match either:
   * Any of the listed requesting groups (for the target user) and/or any of the listed access levels (roles) on the resource or group (`group_ids` and `role_remote_ids` in the API); if both groups and access levels are set on the same configuration, both must match.
   * An [OpalScript](https://docs.opal.dev/docs/opalscript-overview.md) **Request Configuration** script (`opal_script_id` in the API), which is mutually exclusive with group and role conditions on the same configuration.
2. If no conditional configuration matches, use the **default** configuration.

Rules for the list of configurations (UI, API, and Terraform):

| Rule | Detail |
| - | - |
| Default is required | Exactly one default configuration must exist. It has **no condition** and **priority `0`**. |
| Priority `0` is reserved | Only the default may use priority `0`. Conditional configurations must use `1`, `2`, `3`, … |
| Priorities are unique | You cannot attach two configurations with the same priority to the same resource or group. |
| Priorities are contiguous | Priorities must form a sequence starting at `0` with no gaps. For example, `0` and `2` without `1` is rejected. |

**No match:** If the target user does not match any conditional configuration, Opal uses the priority-`0` default.

**Multi-match:** Opal does not merge configurations. If several conditions could match, the **lowest priority number among the matching conditional configurations** (for example `1` before `2`) is used, and the rest are ignored.

For how multiple configurations interact when requesting access **on behalf of** another user, see [Request on behalf rules](https://docs.opal.dev/docs/request-on-behalf.md).

### Custom notification text

To send users notifications when they are approved for resources or groups, check the **Include custom notification text with approvals** checkbox in the request configuration or template, then specify a custom message. You can also toggle **Require reason to forfeit** on a resource, group, or configuration template (`requires_forfeit_reason` in the REST API) to require users to enter a reason before forfeiting their access, or toggle **Disable forfeiting access** to prevent users from forfeiting their own access.

![](https://mintcdn.com/opalsecurity/fu-nWazMe1LxLhxi/images/docs/2f63c57859fe473948967c2d7c5b7b9c60de54a9351ad9702f60731c9de993cf-Screenshot_2024-10-14_at_4.28.52_PM.png?fit=max\&auto=format\&n=fu-nWazMe1LxLhxi\&q=85\&s=56c47153805efa8f64b3ece0f5b09196)

### Approval flow

In the **Approval Flow** section, admins can:

1. Set approval logic to **Auto-Approve**. When this setting is enabled, access requests are automatically approved.

![2262](https://mintcdn.com/opalsecurity/lwwIeFbsleftxaXx/images/docs/b8de301-auto-approve.png?fit=max\&auto=format\&n=lwwIeFbsleftxaXx\&q=85\&s=7fe1b140c40bcd6cb2bb8b01a356c549)

2. Configure an **Approval Workflow**.

* You can include up to three approval **stages**.

* Within each stage, approvers can be the requester's **Manager**, an **Owner**, an [**OpalScript**](https://docs.opal.dev/docs/opalscript-overview.md), or a [**Service User Automation**](https://docs.opal.dev/reference/authentication.md#using-the-api-with-opal-service-users).

* If multiple approvers are selected, admins can choose to require **All** or **Any** reviewers.

  > * **All**: All reviewers must approve the access request to proceed to the next stage. This is **AND** logic.
  > * **Any**: Any reviewers can approve before the access request proceeds to the next stage. This is **OR** logic.

  ![](https://mintcdn.com/opalsecurity/acfYXMo6zBGl_X3L/images/docs/75067385455d4b31e91e3c39906233ab64d6262aa578a508abb2a6f3444d15fd-image.png?fit=max\&auto=format\&n=acfYXMo6zBGl_X3L\&q=85\&s=881d447331d28aa1107414caa92a19f0)

## Automate Approvals with Service Users

Service Users can be assigned as request reviewers to automate approvals based on dynamic conditions. This can be integrated with your own tooling to evaluate if users are compliant with your access policies, such as if security training is complete or if the user is in their authorized work location.

![](https://mintcdn.com/opalsecurity/mtcaBW7jiUNWhl9m/images/docs/cd622b6e2023601fa526673fe5d7ef6749e4484be2ed0543611254157937c34b-Screenshot_2025-10-29_at_8.56.34PM.png?fit=max\&auto=format\&n=mtcaBW7jiUNWhl9m\&q=85\&s=4c2d104ac73571abf5dd97eadb833fc5)

When assigning a service user to a request, an automation is configured for that service user. An automation consists of:

1. **When** the automation is triggered. For access requests, use **Assigned to request**.
2. **Then** the action that is taken. For access requests, use **Send webhook**.
3. **Endpoint** that a webhook is sent to. The webhook handler must be able to make Opal API calls to provide an approve, deny, or comment decision.
4. **HMAC Secret** that is used to sign the webhook payload.

![](https://mintcdn.com/opalsecurity/acfYXMo6zBGl_X3L/images/docs/8d45c6c0de6eef6768f6c0059ea8e4265d77418cecef8df6ce17ab8f50ea15bd-Screenshot_2025-10-29_at_8.59.01PM.png?fit=max\&auto=format\&n=acfYXMo6zBGl_X3L\&q=85\&s=85f36dd99ce2054c1963692eff70083a)

The payload sent in the webhook is:

```json json theme={null}
{
  "created_at": "2025-10-30T01:09:29.332217Z",
  "custom_fields_responses": [],
  "duration_minutes": 60,
  "id": "47cfe906-cf21-4c70-9b76-bf4c749fc4da",
  "reason": "I need admin access to change the branch protection rules.",
  "requested_items_list": [
    {
      "access_level_name": "admin",
      "access_level_remote_id": "admin",
      "name": "another-repo",
      "resource_id": "50031716-6485-4998-bb11-8fb1360385da"
    }
  ],
  "requester_id": "ee84c7db-42f4-4664-a313-fe6102f20e93",
  "status": "PENDING",
  "target_user_id": "ee84c7db-42f4-4664-a313-fe6102f20e93",
  "updated_at": "2025-10-30T01:09:29.382338Z"
}
```

Once the webhook is received, you must make an Opal API request as the service user to one of:

* [POST /requests/\{id}/approve ](https://docs.opal.dev/api-reference/requests/post-requests-approve.md)to approve the request.
* [POST /requests/\{id}/comments](https://docs.opal.dev/api-reference/requests/post-requests-comments.md) to add a comment and leave the request open.
* [POST /requests/\{id}/deny](https://docs.opal.dev/api-reference/requests/post-requests-deny.md) to deny the request.

Follow the instructions under ["Using the API with Opal Service Users"](https://docs.opal.dev/reference/authentication.md#using-the-api-with-opal-service-users) when making your API request.

![](https://mintcdn.com/opalsecurity/acfYXMo6zBGl_X3L/images/docs/75067385455d4b31e91e3c39906233ab64d6262aa578a508abb2a6f3444d15fd-image.png?fit=max\&auto=format\&n=acfYXMo6zBGl_X3L\&q=85\&s=881d447331d28aa1107414caa92a19f0)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.