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

# Netskope

> Connect your Netskope tenant to Serval so workflows can read security alerts and events, manage URL block/allow lists, triage DLP and malware incidents, manage SCIM users and groups, and look up URL categorizations.

## About Netskope

[Netskope](https://www.netskope.com) is a SASE/SSE platform: a secure web gateway, CASB, and DLP engine that inspects your organization's cloud and web traffic. Connecting your Netskope tenant to Serval lets workflows read security alerts and events (DLP, malware, policy, UBA, and more), manage URL block/allow lists and deploy the changes, triage DLP and malware incidents (update status and assignment, read forensics, add notes), manage SCIM users and groups, and look up how Netskope categorizes a URL. Serval talks only to your own tenant's address (for example `mycompany.goskope.com`) and attaches your API token to every request as the `Netskope-Api-Token` header - workflow authors never see or handle the token.

**Authentication:** API token (a REST API v2 service-account token, plus your tenant hostname)

**Data sync:** On-demand only. There is no background sync or scheduled polling - Serval calls the Netskope API only when a workflow runs, and verifies the connection with lightweight read-only health checks.

## What the Netskope integration enables

| Capability          | Description                                                                                                                                                                                                                                                                                                                           |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alert & event reads | Query alert, application, audit, network, page, and infrastructure events over a time window, or iterate complete event streams with the cursor-based data-export endpoints (per-type alert feeds: DLP, malware, malicious site, policy, UBA, CTEP, compromised credential, quarantine, remediation, security assessment, watchlist). |
| Incident triage     | Update DLP/malware incident status, severity, and assignment, read DLP incident forensics, add and list incident notes, and fetch malware analysis reports.                                                                                                                                                                           |
| URL lists           | List, create, update, patch, and delete URL lists, upload a list file, and deploy pending list changes to enforcement.                                                                                                                                                                                                                |
| SCIM users & groups | List, create, update, and delete SCIM users and groups - the access-management surface for provisioning workflows.                                                                                                                                                                                                                    |
| URL lookup          | Ask Netskope how it categorizes a set of URLs.                                                                                                                                                                                                                                                                                        |
| Raw API access      | A flexible "Netskope API request" action covering every endpoint in the curated REST API v2 surface.                                                                                                                                                                                                                                  |

The curated surface is a subset of the full [Netskope REST API v2](https://docs.netskope.com/en/rest-api-v2-overview-312207/); the tenant's built-in API documentation (Swagger) lists everything the platform exposes.

## Get your credentials

Serval needs your **tenant hostname prefix** and a **REST API v2 token**.

<Steps>
  <Step title="Note your tenant hostname">
    It's the part of your Netskope URL before `.goskope.com`: for `https://mycompany.goskope.com` the tenant is `mycompany` (regional tenants look like `mycompany.eu`).
  </Step>

  <Step title="Create a service account token">
    In your Netskope tenant, go to **Settings > Administration > Administrators & Roles > Administrators** and create a **Service Account**. Netskope issues the REST API v2 token when the service account is created.
  </Step>

  <Step title="Scope the token">
    Netskope tokens are scoped per endpoint at creation. Grant, at minimum, read on `/api/v2/events/data/alert` (used by the connection health check), and add the endpoints your workflows will call: the other event and data-export endpoints for ingestion, `/api/v2/policy/urllist` (read-write) for list automation, the `/api/v2/scim/*` endpoints for user/group management, and the `/api/v2/incidents/*` endpoints for triage.
  </Step>

  <Step title="Allowlist Serval's egress IPs (if applicable)">
    If IP allowlisting is enabled on the tenant, add Serval's egress IPs to the Custom IP list (contact [support@serval.com](mailto:support@serval.com) for the list), or route the connection through a self-hosted worker.
  </Step>
</Steps>

## Connect Netskope to Serval

<Steps>
  <Step title="Open the connect catalog">
    In Serval, add a new connection and choose **Netskope** (shown with a Beta label).
  </Step>

  <Step title="Enter the Tenant">
    Enter only the hostname prefix - `mycompany` for `mycompany.goskope.com`. Values containing `.goskope.com`, a scheme like `https://`, or uppercase letters are rejected.
  </Step>

  <Step title="Paste the API token">
    Paste the REST API v2 token from the service account you created.
  </Step>

  <Step title="Name the instance">
    Give the connection a name (for example `Production`) so multiple Netskope tenants stay distinguishable.
  </Step>

  <Step title="Save the connection">
    Serval builds your tenant's address from the prefix and runs the health checks below to confirm it can reach the Netskope API with your token.
  </Step>
</Steps>

<Tip>
  When you edit an existing connection, the stored token appears masked. Leave it as is to keep the existing token; to rotate it, replace the masked value with the entire new token.
</Tip>

## Verifying the connection

The Netskope connection ships with four health checks. They also run again automatically whenever you save changes to the connection's settings.

* **Validate Netskope API connection** - reads one alert event from the last hour. On failure, verify the tenant hostname, that the token is valid, and that the token's scope includes `/api/v2/events/data/alert`.
* **List URL lists** - confirms the token can read URL lists, and reports how many were found.
* **List SCIM users** - confirms the token can read SCIM users.
* **Read audit events** - confirms the token can read the admin audit trail.

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="The tenant is the bare hostname prefix, not a URL">
    Enter only the prefix - `mycompany` for `mycompany.goskope.com`, or `mycompany.eu` for a regional tenant. Serval builds the full tenant address from it and only ever sends your token to your own goskope.com subdomain.
  </Accordion>

  <Accordion title="Tokens are scoped per endpoint">
    A Netskope REST API v2 token only works for the endpoints selected when it was created. If some health checks pass while others fail - or workflows fail on specific endpoints with valid credentials - the token is missing that endpoint's scope. Edit the service account's token scope in the Netskope tenant, or create a new token and rotate it into the connection.
  </Accordion>

  <Accordion title="A 401 with a valid token can mean IP allowlisting">
    If the tenant enforces IP allowlisting, requests from non-allowlisted addresses fail even with a valid token. Add Serval's egress IPs to the tenant's Custom IP list, or route the connection through a self-hosted worker.
  </Accordion>

  <Accordion title="URL list changes need a deploy">
    Creating or editing a URL list does not change enforcement by itself - pending changes take effect only after calling the deploy endpoint (`POST /api/v2/policy/urllist/deploy`). Workflows that mutate lists should end with a deploy step.
  </Accordion>

  <Accordion title="SCIM endpoints require SCIM to be enabled">
    The `/api/v2/scim/*` endpoints only work on tenants where Netskope's SCIM directory is in use. If the SCIM health check fails while others pass, the tenant may not have SCIM enabled - the rest of the integration works normally.
  </Accordion>

  <Accordion title="The integration is marked Beta">
    Netskope appears with a Beta label in the Serval connect catalog. Functionality described on this page is available today, but the integration's surface may still evolve.
  </Accordion>
</AccordionGroup>

***

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