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

# Opal Security

> Connect Opal Security to Serval so workflows can look up, provision, and revoke access, and file and approve access requests in Opal.

## About Opal Security

Opal Security is an access management platform for governing user access to groups, resources, and applications. Serval connects to Opal with an API token created by an Opal administrator, and workflows can then look up a user's current access, add or remove group membership, and submit, review, and approve access requests. Production (api.opal.dev) and sandbox (sandbox.opal.dev) connect as separate instances, each identified by its API domain.

**Authentication:** API token (bearer) - you provide your Opal API Domain and an API Token.

**Data sync:** On demand only. There is no background sync; Serval calls the Opal API live each time a workflow runs.

## What the Opal Security integration enables

| Capability           | Description                                                                                                                                                                                                                                                                 |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Access management    | Look up, provision, and revoke user access. Includes workflows to get a user's Opal ID by email, view their current group access, resource access, or complete access, check access to a specific resource, and add or remove a user from an Opal group.                    |
| Access requests      | Submit, review, and approve access requests. Includes workflows to request group access for a user, list pending requests, approve a request, and get request details by ID. Group requests go through Opal's normal approval workflow and return a trackable request link. |
| Discovery            | Standalone workflows to list Opal owners (including their users and escalation settings) and to list the groups users can request access to.                                                                                                                                |
| Full Opal API access | Workflows can reach anything in the Opal REST API through Serval's authenticated connection, covering apps, bundles, groups, group bindings, resources, users, owners, access requests, events, sessions, IdP group mappings, and non-human identities.                     |

Anything defined in the [Opal API](https://docs.opal.dev/reference) can be accessed through Serval.

## Get your credentials

You need an API token created by an Opal administrator. The token needs read access to users, groups, and resources for the connection checks to pass, and write or provisioning permission if you plan to use the add/remove-user or access-request workflows. See the [Opal API reference](https://docs.opal.dev/reference) for details on Opal's API tokens.

<Steps>
  <Step title="Open the API Tokens settings in Opal">
    Sign in to Opal and open your organization's Settings page, then select the API Tokens section.
  </Step>

  <Step title="Create a token">
    Click Create Token, give it a descriptive name (for example, "Serval Integration"), and select the permissions appropriate for your use case.
  </Step>

  <Step title="Copy the token immediately">
    Copy the generated API Token right away - Opal displays it only once. If you lose it, you will need to create a new token.
  </Step>

  <Step title="Note your API domain">
    Use api.opal.dev for production or sandbox.opal.dev for sandbox.
  </Step>
</Steps>

<Warning>
  Opal shows the token value a single time, at creation. Store it securely before leaving the page.
</Warning>

<Note>
  Read access to users, groups, and resources is required for the post-connect health checks to pass. Provisioning workflows (adding or removing users, approving access requests) additionally need write permission.
</Note>

## Connect in Serval

<Steps>
  <Step title="Open the Opal Security connect form">
    In Serval, find Opal Security in the app catalog and start a new connection. The connect form has two fields.
  </Step>

  <Step title="Enter your API Domain (required)">
    Type the bare domain only, exactly as shown in the placeholder "api.opal.dev". The helper text reads "Your Opal API domain (e.g., api.opal.dev or sandbox.opal.dev)". Do not include a protocol, path, or port. Leaving it blank shows "This field is required". If the domain is not a valid Opal domain, the save fails with "Failed to install integration: Invalid API domain: invalid API domain format: must be a valid Opal domain (e.g., api.opal.dev or sandbox.opal.dev)".
  </Step>

  <Step title="Enter your API Token (required)">
    Paste the full token into the API Token password field (helper text: "Your Opal API bearer token"). The form does not check the token at all - a blank, mistyped, or revoked token still saves, and the problem only surfaces when the health checks run after you connect.
  </Step>

  <Step title="Save and confirm">
    Submit the form, then confirm all four health checks pass (see below). After saving, the token is displayed only as an obfuscated value with its last 4 characters visible.
  </Step>
</Steps>

<Tip>
  Want both production and sandbox? Connect each domain separately - each one is its own connection, identified by its API domain.
</Tip>

<Warning>
  When editing an existing connection, the saved token shows only as an obfuscated value. Use the Replace button (reconnect dialog) or the pencil icon (integration settings page) and paste the complete new token - never a partial value, and never submit a cleared token field. Whenever you change anything about the connection, replace the token in full as part of the same save, then confirm the health checks pass.
</Warning>

## Verifying the connection

The connection ships four health checks that make live calls to Opal:

* **Test Opal Connection** - verifies Serval can authenticate with Opal using your token. Success: "Successfully authenticated with Opal Security". Failure: "Unable to connect to Opal Security. Please verify your API token is valid and has the necessary permissions."
* **List Opal Users** - verifies the token can read user data by listing a small sample of users. Success: "Successfully listed users from Opal Security (sample size: \[number])". Failure: "Unable to list users from Opal Security. Please verify the API token has permission to read user data."
* **List Opal Groups** - verifies the token can read group data by listing a small sample of groups. Success: "Successfully listed groups from Opal Security (sample size: \[number])". Failure: "Unable to list groups from Opal Security. Please verify the API token has permission to read group data."
* **List Opal Resources** - verifies the token can read resource data by listing resources. Success: "Successfully listed resources from Opal Security (sample size: \[number])". Failure: "Unable to list resources from Opal Security. Please verify the API token has permission to read resource data."

<Tip>
  All four checks test read access only. A connection can show all green and still fail provisioning workflows (adding or removing users, approving access requests) if the token lacks write permission. If lookups work but provisioning fails, create a token with write permission in Opal and replace the token on the connection.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Editing or rotating the token: always paste the complete new value">
    On the integration settings page, the saved token shows as an obfuscated value (bullets plus the last 4 characters) with a small pencil (edit) icon next to it. Click the pencil, paste the complete new token into the input (placeholder: "Enter new value"), and click Update. In the reconnect dialog, the same field shows a Replace button instead - click it and paste the full new token there. Either way, always paste the entire token: never submit a cleared or partial token field, and whenever you edit anything else about the connection (for example the API Domain), replace the token in full as part of the same save. Then confirm all four health checks pass.
  </Accordion>

  <Accordion title="Only single-label Opal domains are accepted">
    The API Domain must be exactly one label followed by .opal.dev - for example api.opal.dev or sandbox.opal.dev. Values with a protocol ([https://api.opal.dev](https://api.opal.dev)), a path (api.opal.dev/v1), a multi-level subdomain (foo.bar.opal.dev), or a self-hosted custom domain are rejected. On first connect this surfaces as "Failed to install integration: Invalid API domain: invalid API domain format: must be a valid Opal domain (e.g., api.opal.dev or sandbox.opal.dev)". When editing an existing connection from the integration settings page, the same problem shows as "Failed to update configuration".
  </Accordion>

  <Accordion title="Do not include a version path in the API Domain">
    Serval appends the API version path automatically. Enter the bare domain only - adding "/v1" (or any path) to the API Domain fails validation.
  </Accordion>

  <Accordion title="Token problems appear as health-check failures, not connect errors">
    The token is never validated when you connect - even a blank token saves without an error. A missing or under-permissioned token surfaces afterward: a token that cannot authenticate fails Test Opal Connection, and a token missing read access to users, groups, or resources fails the matching check with a "Please verify the API token has permission to read ... data" message. Fix the token's permissions in Opal, then replace the token on the connection (pencil icon or Replace button) and re-run the checks.
  </Accordion>

  <Accordion title="Opal shows the API token only once">
    The token value is displayed a single time when it is created in Opal. If it is lost, create a new token in Opal and replace the token on the Serval connection, pasting the complete new value.
  </Accordion>

  <Accordion title="Provisioning workflows require approval by default">
    Add User to Opal Group, Remove User from Opal Group, Request Group Access For User in Opal, and Approve Opal Access Request install with installer approval by default - someone must approve each run. Lookup and listing workflows run without approval by default. You can adjust approval settings after installation.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Opal Security integration.