Skip to main content

​
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

Anything defined in the Opal API 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 for details on Opal’s API tokens.
1

Open the API Tokens settings in Opal

Sign in to Opal and open your organization’s Settings page, then select the API Tokens section.
2

Create a token

Click Create Token, give it a descriptive name (for example, “Serval Integration”), and select the permissions appropriate for your use case.
3

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.
4

Note your API domain

Use api.opal.dev for production or sandbox.opal.dev for sandbox.
Opal shows the token value a single time, at creation. Store it securely before leaving the page.
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.

​
Connect in Serval

1

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.
2

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)”.
3

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.
4

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.
Want both production and sandbox? Connect each domain separately - each one is its own connection, identified by its API domain.
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.

​
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.”
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.

​
Gotchas and troubleshooting

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.
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), 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”.
Serval appends the API version path automatically. Enter the bare domain only - adding “/v1” (or any path) to the API Domain fails validation.
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.
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.
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.
Need help? Contact support@serval.com for assistance with your Opal Security integration.