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

# Obsidian Security

> Obsidian Security is a SaaS security posture management (SSPM) platform - connect it to Serval so workflows can read intelligence alerts, accounts, connected services, activity events, and posture and compliance data, and update alerts as part of triage automation.

## 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. This integration is currently in **Beta**.

**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

| Capability                   | Description                                                                                                                                                                                               |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Obsidian Security API access | The built-in "Obsidian Security API request" action sends any query supported by Obsidian's GraphQL API to your tenant's regional endpoint, for both reads and writes.                                    |
| Intelligence alerts          | Read security intelligence alerts (including id, ticket id, name, and severity, ordered by generation time) and automate triage with updates to alert status, state, resolution tags, and alert comments. |
| Accounts and entities        | Query the entity catalog - accounts, entities, and aggregate views - across all the services connected to Obsidian.                                                                                       |
| Connected services           | List the cloud services your organization has connected to Obsidian Security.                                                                                                                             |
| Activity events              | Search the collected activity event stream, fetch individual events, and run event aggregations.                                                                                                          |
| Posture and compliance       | Read and manage posture rules and settings, plus compliance standards, controls, mappings, and reports (including create, update, and clone operations).                                                  |
| Health checks                | Four built-in health checks validate the connection and the token's read access to connected services, accounts, and intelligence alerts.                                                                 |

Anything defined in the [Obsidian Security API](https://docs.obsidiansecurity.com/obsidian/api/graphql) 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](https://docs.obsidiansecurity.com/obsidian/settings/api-access-tokens).

<Steps>
  <Step title="Open API Access Tokens in Obsidian Security">
    Log in to your Obsidian Security tenant and navigate to **Settings**, then **API Access Tokens**.
  </Step>

  <Step title="Create a token">
    Create a new token and give it a descriptive name such as "Serval Integration".
  </Step>

  <Step title="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.
  </Step>

  <Step title="Copy the token immediately">
    Copy the token right away and keep it somewhere safe until you've pasted it into Serval.
  </Step>

  <Step title="Confirm your tenant's region">
    Check whether your tenant is hosted in the US, EU, or AU - see Obsidian's [server endpoints documentation](https://docs.obsidiansecurity.com/obsidian/api/rest#server-endpoints). You'll select the matching region in Serval.
  </Step>
</Steps>

<Warning>
  Obsidian shows the full token only once, at creation time. If you lose it, you must generate a new one.
</Warning>

<Note>
  Tokens are tenant-bound: a token created in one region's tenant will not authenticate against another region's endpoint.
</Note>

## Connect in Serval

<Steps>
  <Step title="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.
  </Step>

  <Step title="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).
  </Step>

  <Step title="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).
  </Step>
</Steps>

<Note>
  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.
</Note>

## 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."

<Tip>
  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.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="The connection is green but a workflow fails with a permission error">
    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.
  </Accordion>

  <Accordion title="Region must exactly match your tenant">
    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.
  </Accordion>

  <Accordion title="The intelligence health check fails on a brand-new tenant">
    "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.
  </Accordion>

  <Accordion title="It's a GraphQL-only API">
    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.
  </Accordion>

  <Accordion title="Connections are named by region, not tenant">
    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.
  </Accordion>

  <Accordion title="Beta integration">
    Obsidian Security is flagged as Beta in the Serval connect UI. It is fully usable, but details may still evolve.
  </Accordion>
</AccordionGroup>

***

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