Skip to main content

​
About Obsidian Security

Obsidian Security is a SaaS security posture management (SSPM) platform that monitors your connected cloud applications, generates security intelligence alerts, and tracks posture and compliance state. Connecting it to Serval lets workflows read intelligence alerts, query accounts and entities, list connected services, search activity events, read posture and compliance data, and perform write operations such as updating alert status. Authentication: API token (bearer). You pick the regional API endpoint that matches your Obsidian Security tenant and paste an API access token created in Obsidian Security. Serval stores the token server-side and attaches it to requests for you - it is never exposed to workflow code, and it is only ever sent to Obsidian’s own regional API domains. Data sync: On demand. There is no background sync or scheduled ingestion - workflows, actions, and health checks call the Obsidian Security API at the moment they run, and nothing is pulled into Serval on a schedule.

​
What the Obsidian Security integration enables

Anything defined in the Obsidian Security API can be accessed through Serval.

​
Get your credentials

Serval connects with an API access token created in your Obsidian Security tenant, plus the regional API endpoint your tenant is hosted on. Obsidian documents token creation in its API Access Tokens guide.
1

Open API Access Tokens in Obsidian Security

Log in to your Obsidian Security tenant and navigate to Settings, then API Access Tokens.
2

Create a token

Create a new token and give it a descriptive name such as “Serval Integration”.
3

Grant the token read access

Grant read access to the data your Serval workflows will use - at minimum connected services, accounts/entities, and intelligence (alerts), which is what the shipped health checks exercise. Add read or write access for anything else your workflows touch (activity events, posture, compliance). Workflows that read data outside the token’s scope fail at runtime with a permission error.
4

Copy the token immediately

Copy the token right away and keep it somewhere safe until you’ve pasted it into Serval.
5

Confirm your tenant's region

Check whether your tenant is hosted in the US, EU, or AU - see Obsidian’s server endpoints documentation. You’ll select the matching region in Serval.
Obsidian shows the full token only once, at creation time. If you lose it, you must generate a new one.
Tokens are tenant-bound: a token created in one region’s tenant will not authenticate against another region’s endpoint.

​
Connect in Serval

1

Region (required)

“Select the regional API endpoint that matches your Obsidian Security tenant.” A dropdown with exactly three options - US (api.obsec.io), EU (api.obsec.eu), and AU (api.sy.obsec.io) - defaulting to US. Pick the region you confirmed in the previous section.
2

API Token (required)

“Bearer token generated in Obsidian Security under Settings -> API Access Tokens.” Paste the token you copied. There is no format check on this field - the token’s validity is proven by the health checks after you save. Once saved, it displays masked (bullet characters plus the last 4 characters).
3

Save and verify

Save the connection, then run the health checks below to confirm everything works. If saving fails, the error appears as “Failed to install integration: [reason]” (or “Failed to update integration: [reason]” when editing).
Editing the connection later: the saved token displays masked and only changes when you type a new value - leaving the masked value untouched, or clearing the token field to blank, keeps your stored token, so you can safely change the Region without retyping it. That said, because tokens are tenant-bound, changing the Region generally means you need a new token from that region’s tenant anyway.

​
Verifying the connection

The Obsidian Security integration ships four health checks: Validate Obsidian Security API connection - verifies the configured token can reach the Obsidian Security API by querying the API version.
  • Success: “Successfully connected to Obsidian Security API.”
  • Failure: “Unable to connect to the Obsidian Security API. Verify that the API token is valid and the selected region matches your tenant.”
List connected services in Obsidian Security - verifies the token can list the cloud services your organization has connected to Obsidian.
  • Success: “Successfully retrieved [number] connected service(s) from Obsidian Security.”
  • Failure: “Unable to list connected services. Verify the API token has read access to the Obsidian Security service catalog.”
List accounts in Obsidian Security - verifies the token can read the entity/accounts catalog by fetching a single account.
  • Success: “Successfully read accounts from Obsidian Security (returned [number] record(s)).”
  • Failure: “Unable to read accounts from Obsidian Security. The API token may lack permission to query the entity catalog.”
List intelligence alerts in Obsidian Security - verifies the token can read security intelligence by fetching the most recent alert.
  • Success: “Successfully read intelligence from Obsidian Security (returned [number] alert(s)).”
  • Failure: “Unable to read intelligence alerts. The API token may lack permission to query intelligence, or no alerts exist yet.”
If “Validate Obsidian Security API connection” passes but one of the list checks fails, your token and region are fine - the token just lacks read access to that data. Edit the token’s permissions in Obsidian Security under Settings, then API Access Tokens, granting read access to connected services, accounts/entities, and intelligence.

​
Gotchas and troubleshooting

The connection check only proves the token is valid for your region. Each kind of data (intelligence, accounts/entities, connected services, events, posture, compliance) needs its own read access on the token. A workflow that touches data outside the token’s scope fails at runtime with a permission error - broaden the token’s access in Obsidian Security and re-run.
Serval accepts exactly three regional domains: api.obsec.io (US), api.obsec.eu (EU), and api.sy.obsec.io (AU). The connect form’s dropdown only offers those three values, so you can’t mistype one in the UI - but a connection created programmatically must pass exactly one of those lowercase host values. Anything else - including a value with an https:// prefix or uppercase letters - is rejected with the error ‘unsupported Obsidian Security API domain “[value]”; must be one of api.obsec.io (US), api.obsec.eu (EU), or api.sy.obsec.io (AU)’. And because tokens are tenant-bound, switching the Region usually means generating a new token in that region’s tenant too.
“Unable to read intelligence alerts. The API token may lack permission to query intelligence, or no alerts exist yet.” has two possible causes - a missing token permission, or simply that your tenant has not generated any alerts yet. On a fresh tenant with no alerts, this failure is not necessarily a credentials problem.
Obsidian Security exposes a single GraphQL API rather than a catalog of individual REST endpoints, so Serval ships no enumerated endpoint list for this integration. Workflows reach everything through the generic “Obsidian Security API request” action. If the API accepts a request but reports problems, the action fails with “Obsidian Security GraphQL request returned errors:” followed by each error message the API returned, joined by semicolons.
The connection is labeled by the selected regional domain (for example, api.obsec.io). If you maintain multiple Obsidian Security connections, they are distinguished by region - not by a tenant name you choose.
Need help? Contact support@serval.com for assistance with your Obsidian Security integration.