Netskope Cloud Exchange exposes a REST API to enable nearly every equivalent GUI command to be programmatically triggered. However, each REST API call requires valid credentials. Users who are given API access will be able to create a Client ID and Client Secret. Note, this is NOT the same API token that you use for communicating with your Netskope tenant.
You can create API tokens by going to Settings > Users and clicking on the API Tokens tab.
- You can create new API tokens by clicking Create new token, which opens a form to create new tokens at the same credentialed level as the user has in the UI.
- Users can fill in a description and expiry days for the token.
- You can copy the Client Secret using the copy button, and Client ID and Client Secret can be used to access Cloud Exchange APIs.
After the tokens are created, copy them and return to the Configure New Tenant page. Please note, a v1 token is required for adding a Netskope tenant in Cloud Exchange but will not be used if a v2 endpoint is available
You can use the iterator API endpoint by enabling the toggle button Use Iterator Endpoint. The toggle button will only be accessible if you have a provided a v2 token. If you opt for the Iterator API endpoints, all the Threat IoCs, Alerts, and Events will be fetched by the Iterator API endpoints. You have to provide access to the above mentioned API endpoints while generating the v2 API token.
To view the API documentation in Swagger, click Help at the bottom of the left panel and select API docs. To authorize in the API docs with a username and password or with an API token, see Help.
 |
Click the caret icon to view endpoint information.
REST API Scopes
The Cloud Exchange platform REST API scopes are explained in the following sections.
Important
From 6.0.0 onwards, use the RBAC v3 token with the role Netskope Cloud Exchange. To generate the RBAC v3 token, refer to the steps provided here.
5.1.1 and 5.1.2 REST API
v1 REST API Scopes
| Netskope Endpoints | Privilege Level | Log Shipper (CLS) | Ticket Orchestrator (CTO) | Threat Exchange (CTE) | Risk Exchange (CREv2) |
|---|---|---|---|---|---|
| /api/v1/updateFileHashList | Read + Write (v1 default) | Used to share hashes to Netskope tenant. | |||
| /api/v1/app_instances | Read + Write (v1 default) | Used to share app instances to Netskope tenant. | |||
| /api/v1/app_instances | Read + Write (v1 default) | It is a required endpoint and used to validate v1 token during tenant configuration with v1 token. | |||
v2 REST API Scopes
| Netskope Endpoints | Privilege Level | Log Shipper (CLS) | Ticket Orchestrator (CTO) | Threat Exchange (CTE) | Risk Exchange (CREv2) |
|---|---|---|---|---|---|
| /api/v2/events/dataexport/ events/alert | Read | It is a required endpoint and it is used to validate v2 token during tenant configuration. | |||
| /api/v2/events/dataexport/ events/application | Read | Used to pull and ingest application events. | Used to pull, extract and store applications for APPLICATION entity. | ||
| /api/v2/events/dataexport/ events/audit | Read | Used to pull and ingest audit events. | |||
| /api/v2/events/dataexport/ events/endpoint | Read | Used to pull and ingest endpoint data. | Used to pull and store endpoint data. | ||
| /api/v2/events/dataexport/ events/incident | Read | Used to pull and ingest incident events. | Used to pull and store incident data. | ||
| /api/v2/events/dataexport/ events/infrastructure | Read | Used to pull infrastructure events. | |||
| /api/v2/events/dataexport/ events/network | Read | Used to pull network events. | |||
| /api/v2/events/dataexport/ events/page | Read | Used to pull page events. | |||
| /api/v2/events/dataexport/ alerts/uba | Read | Used to pull and ingest UBA alerts. | Used to pull and store UBA alerts. | Used to pull and extract user information from UBA alerts for USER entity. | |
| /api/v2/events/dataexport/ alerts/securityassessment | Read | Used to pull and ingest Security assessment alerts. | Used to pull and store Security assessment alerts. | ||
| /api/v2/events/dataexport/ alerts/quarantine | Read | Used to pull and ingest Quarantine alerts. | Used to pull and store Quarantine alerts. | ||
| /api/v2/events/dataexport/ alerts/remediation | Read | Used to pull and ingest Remediation alerts. | Used to pull and store Remediation alerts. | ||
| /api/v2/events/dataexport/ alerts/policy | Read | Used to pull and ingest Policy alerts. | Used to pull and store Policy alerts. | ||
| /api/v2/events/dataexport/ alerts/malware | Read | Used to pull and ingest Malware alerts. | Used to pull and store Malware alerts. | Used to pull and extract hashes from Malware alerts. | |
| /api/v2/events/dataexport/ alerts/malsite | Read | Used to pull and ingest Malsite alerts. | Used to pull and store Malsite alerts. | Used to pull and extract malicious URL(s) from Malsite alerts. | |
| /api/v2/events/dataexport/ alerts/compromisedcredential | Read | Used to pull and ingest Compromised credential alerts. | Used to pull and store Compromised credential alerts. | ||
| /api/v2/events/dataexport/ alerts/ctep (or ips) | Read | Used to pull and ingest ctep/ips/c2 alerts. | Used to pull and store ctep/ips/c2 alerts. | ||
| /api/v2/events/dataexport/ alerts/dlp | Read | Used to pull and ingest DLP alerts. | Used to pull and store DLP alerts. | ||
| /api/v2/events/dataexport/ alerts/watchlist | Read | Used to pull and ingest Watchlist alerts. | Used to pull and store Watchlist alerts. | ||
| /api/v2/events/token/ transaction_events | Read | Used to pull subscription key and subscription path for Netskope WebTx Configuration and its used to authenticate to pull WebTx data. | |||
| /api/v2/events/metrics/ transactionevents | Read | Used to pull backlog message count for WebTx configuration. | |||
| /api/v2/incidents/update | Read + Write | Used to update incidents back to Netskope tenant. | |||
| /api/v2/policy/urllist | Read + Write | Used to share urls, domains, ip address to Url list in Netskope tenant. | |||
| /api/v2/policy/urllist/ deploy | Read + Write | Used to deploy changes which are shared using /api/v2/policy/urllist endpoint. | |||
| /api/v2/incidents/uba/ getuci | Read + Write | Used to pull score for user entity. | |||
| /api/v2/incidents/user/ uciimpact | Read + Write | Used to ingest impact UCI score for user to Netskope tenant. | |||
| /api/v2/services/cci/ app | Read | Used to pull CCI related application details like app name, CCI, CCL, category name & organization. | |||
| /api/v2/services/cci/ domain | Read | Used to fetch the domain details for applications. | |||
| /api/v2/services/cci/ tags | Read | Used to fetch tags details for applications. | |||
| /api/v2/infrastructure/ publishers | Read + Write | Used to get list of available publishers. | Used to get list of available publishers. | ||
| /api/v2/steering/apps/ private | Read + Write | Used to share private apps and its details. | Used to share private apps and its details. | ||
| /api/v2/scim/Users | Read + Write | Used to get SCIM users. | |||
| /api/v2/scim/Groups | Read + Write | Used to get SCIM groups and change/add/delete users from a group. | |||
| /api/v2/events/dataexport/ alerts/device | Read | Used to pull Device alerts. (required minimum Cloud Exchange v5.1.0, Netskope Tenant plugin v1.2.0 and CLS plugin v2.1.0) | Used to pull and store Device alerts. (required Cloud Exchange v5.1.0, Netskope Tenant plugin v1.2.0 and CTO plugin v2.1.0) | ||
| /api/v2/events/dataexport/ alerts/content | Read | Used to pull Content alerts. (required minimum Cloud Exchange v5.1.0, Netskope Tenant plugin v1.2.0 and CLS plugin v2.1.0) | Used to pull and store Content alerts. (required Cloud Exchange v5.1.0, Netskope Tenant plugin v1.2.0 and CTO plugin v2.1.0) | ||
| /api/v2/events/dataexport/ iterator | Read + Write | Used to Check Status/Fetch data/Delete Client Status Iterator. (required minimum Cloud Exchange v5.1.1, Netskope Tenant plugin v1.4.0 and CLS plugin v2.2.0) | |||
| /api/v2/incidents/dlpincidents | Read | Used to pull Incident Forensics per dlp_incident_id. (required minimum Cloud Exchange v5.1.2, Netskope Tenant plugin v1.5.0 and CLS plugin v2.3.0) | Used to pull and store Incident Forensics per dlp_incident_id. (required minimum Cloud Exchange v5.1.2, Netskope Tenant plugin v1.5.0 and CTO plugin v2.3.0) | ||
| /api/v2/incidents/users/uci/reset | Read +Write | Used to reset UCI score for user to Netskope tenant. | |||
| /api/v2/nsiq/retrohunt/ioc/getinfo | Read + Write | Used to get the retrohunt information of IOCs in batch. | |||
| /api/v2/nsiq/retrohunt/ioc/report | Read | Used to get the retrohunt report of IOC. | |||
| /api/v2/nsiq/retrohunt/ioc/info | Read | Used to get the retrohunt information of IOC. | |||
5.1.0 REST API
v1 REST API Scopes
| Netskope Endpoints | Privilege Level | Log Shipper (CLS) | Ticket Orchestrator (CTO) | Threat Exchange (CTE) | Risk Exchange (CREv2) |
|---|---|---|---|---|---|
| /api/v1/updateFileHashList | Read + Write (v1 default) | Used to share hashes to Netskope tenant. | |||
| /api/v1/app_instances | Read + Write (v1 default) | Used to share app instances to Netskope tenant. | |||
| /api/v1/app_instances | Read + Write (v1 default) | It is a required endpoint and used to validate v1 token during tenant configuration with v1 token. | |||
v2 REST API Scopes
| Netskope Endpoints | Privilege Level | Log Shipper (CLS) | Ticket Orchestrator (CTO) | Threat Exchange (CTE) | Risk Exchange (CREv2) |
|---|---|---|---|---|---|
| /api/v2/events/dataexport/ events/alert | Read | It is a required endpoint and it is used to validate v2 token during tenant configuration. | |||
| /api/v2/events/dataexport/ events/application | Read | Used to pull and ingest application events. | Used to pull, extract and store applications for APPLICATION entity. | ||
| /api/v2/events/dataexport/ events/audit | Read | Used to pull and ingest audit events. | |||
| /api/v2/events/dataexport/ events/endpoint | Read | Used to pull and ingest endpoint data. | Used to pull and store endpoint data. | ||
| /api/v2/events/dataexport/ events/incident | Read | Used to pull and ingest incident events. | Used to pull and store incident data. | ||
| /api/v2/events/dataexport/ events/infrastructure | Read | Used to pull infrastructure events | |||
| /api/v2/events/dataexport/ events/network | Read | Used to pull network events | |||
| /api/v2/events/dataexport/ events/page | Read | Used to pull page events | |||
| /api/v2/events/dataexport/ alerts/uba | Read | Used to pull and ingest UBA alerts | Used to pull and store UBA alerts. | Used to pull and extract user information from UBA alerts for USER entity. | |
| /api/v2/events/dataexport/ alerts/securityassessment | Read | Used to pull and ingest Security assessment alerts | Used to pull and store Security assessment alerts. | ||
| /api/v2/events/dataexport/ alerts/quarantine | Read | Used to pull and ingest Quarantine alerts | Used to pull and store Quarantine alerts. | ||
| /api/v2/events/dataexport/ alerts/remediation | Read | Used to pull and ingest Remediation alerts | Used to pull and store Remediation alerts. | ||
| /api/v2/events/dataexport/ alerts/policy | Read | Used to pull and ingest Policy alerts | Used to pull and store Policy alerts. | ||
| /api/v2/events/dataexport/ alerts/malware | Read | Used to pull and ingest Malware alerts | Used to pull and store Malware alerts. | Used to pull and extract hashes from Malware alerts. | |
| /api/v2/events/dataexport/ alerts/malsite | Read | Used to pull and ingest Malsite alerts | Used to pull and store Malsite alerts. | Used to pull and extract malicious URL(s) from Malsite alerts. | |
| /api/v2/events/dataexport/ alerts/compromisedcredential | Read | Used to pull and ingest Compromised credential alerts | Used to pull and store Compromised credential alerts. | ||
| /api/v2/events/dataexport/ alerts/ctep (or ips) | Read | Used to pull and ingest ctep/ips/c2 alerts | Used to pull and store ctep/ips/c2 alerts. | ||
| /api/v2/events/dataexport/ alerts/dlp | Read | Used to pull and ingest DLP alerts | Used to pull and store DLP alerts. | ||
| /api/v2/events/dataexport/ alerts/watchlist | Read | Used to pull and ingest Watchlist alerts | Used to pull and store Watchlist alerts. | ||
| /api/v2/events/token/ transaction_events | Read | Used to pull subscription key and subscription path for Netskope WebTx Configuration and its used to authenticate to pull WebTx data. | |||
| /api/v2/events/metrics/ transactionevents | Read | Used to pull backlog message count for WebTx configuration. | |||
| /api/v2/incidents/update | Read + Write | Used to update incidents back to Netskope tenant. | |||
| /api/v2/policy/urllist | Read + Write | Used to share urls, domains, ip address to Url list in Netskope tenant. | |||
| /api/v2/policy/urllist/ deploy | Read + Write | Used to deploy changes which are shared using /api/v2/policy/urllist endpoint. | |||
| /api/v2/incidents/uba/ getuci | Read + Write | Used to pull score for user entity. | |||
| /api/v2/incidents/user/ uciimpact | Read + Write | Used to ingest impact UCI score for user to Netskope tenant | |||
| /api/v2/services/cci/ app | Read | Used to pull CCI related application details like app name, CCI, CCL, category name & organization. | |||
| /api/v2/services/cci/ domain | Read | Used to fetch the domain details for applications. | |||
| /api/v2/services/cci/ tags | Read | Used to fetch tags details for applications. | |||
| /api/v2/infrastructure/ publishers | Read + Write | Used to get list of available publishers. | Used to get list of available publishers. | ||
| /api/v2/steering/apps/ private | Read + Write | Used to share private apps and its details | Used to share private apps and its details. | ||
| /api/v2/scim/Users | Read + Write | Used to get SCIM users. | |||
| /api/v2/scim/Groups | Read + Write | Used to get SCIM groups and change/add/delete users from a group. | |||
5.0.1 REST API (Deprecated)
v1 REST API Scopes
| Netskope Endpoint Permissions | Privilege Level | Log Shipper (CLS) | Ticket Orchestrator (CTO) | Threat Exchange (CTE) | User Risk Exchange (URE) | App Risk Exchange (ARE) |
|---|---|---|---|---|---|---|
| /api/v1/updateFileHashList | Read + Write (v1 default) | x |
v2 REST API Scopes
| Netskope Endpoint Permissions | Privilege Level | Log Shipper (CLS) | Ticket Orchestrator (CTO) | Threat Exchange (CTE) | User Risk Exchange (URE) | App Risk Exchange (ARE) |
|---|---|---|---|---|---|---|
| /api/v2/events/dataexport/events/alert | Read | |||||
| /api/v2/events/dataexport/events/application | Read | x | x | |||
| /api/v2/events/dataexport/events/audit | Read | x | ||||
| /api/v2/events/dataexport/events/connection | Not polled | |||||
| /api/v2/events/dataexport/events/incident | Read | x | ||||
| /api/v2/events/dataexport/events/infrastructure | Read | x | ||||
| /api/v2/events/dataexport/events/network | Read | x | ||||
| /api/v2/events/dataexport/events/page | Read | x | ||||
| /api/v2/events/dataexport/alerts/uba | Read | x | x | x | ||
| /api/v2/events/dataexport/alerts/securityassessment | Read | x | x | |||
| /api/v2/events/dataexport/alerts/quarantine | Read | x | x | |||
| /api/v2/events/dataexport/alerts/remediation | Read | x | x | |||
| /api/v2/events/dataexport/alerts/policy | Read | x | x | |||
| /api/v2/events/dataexport/alerts/malware | Read | x | x | x | ||
| /api/v2/events/dataexport/alerts/malsite | Read | x | x | x | ||
| /api/v2/events/dataexport/alerts/compromisedcredential | Read | x | x | |||
| /api/v2/events/dataexport/alerts/ctep (or ips) | Read | x | x | |||
| /api/v2/events/dataexport/alerts/dlp | Read | x | x | |||
| /api/v2/events/dataexport/alerts/watchlist | Read | x | x | |||
| /api/v2/policy/urllist/file | Read + Write | |||||
| /api/v2/policy/urllist | Read + Write | x | ||||
| /api/v2/policy/urllist/deploy | Read + Write | x | ||||
| /api/v2/incidents/uba/getuci | Read + Write | x | ||||
| /api/v2/ubadatasvc/user/uci | Read + Write | x | ||||
| /api/v2/services/cci/app | Read | x | ||||
| /api/v2/services/cci/domain | Read | x | ||||
| /api/v2/services/cci/tags | Read | x | ||||
| /api/v2/infrastructure/publishers | Read + Write | x | ||||
| /api/v2/steering/apps/private/tags | Read + Write | x | ||||
| /api/v2/steering/apps/private | Read + Write | x |
5.0.0 REST API (Deprecated)
v1 REST API Scopes
| Netskope Endpoint Permissions | Privilege Level | Log Shipper (CLS) | Ticket Orchestrator (CTO) | Threat Exchange (CTE) | User Risk Exchange (URE) | App Risk Exchange (ARE) |
|---|---|---|---|---|---|---|
| /api/v1/updateFileHashList | Read + Write (v1 default) | x |
v2 REST API Scopes
| Netskope Endpoint Permissions | Privilege Level | Log Shipper (CLS) | Ticket Orchestrator (CTO) | Threat Exchange (CTE) | User Risk Exchange (URE) | App Risk Exchange (ARE) |
|---|---|---|---|---|---|---|
| /api/v2/events/dataexport/events/alert | Read | |||||
| /api/v2/events/dataexport/events/application | Read | x | x | |||
| /api/v2/events/dataexport/events/audit | Read | x | ||||
| /api/v2/events/dataexport/events/connection | Not polled | |||||
| /api/v2/events/dataexport/events/incident | Read | x | ||||
| /api/v2/events/dataexport/events/infrastructure | Read | x | ||||
| /api/v2/events/dataexport/events/network | Read | x | ||||
| /api/v2/events/dataexport/events/page | Read | x | ||||
| /api/v2/events/dataexport/alerts/uba | Read | x | x | x | ||
| /api/v2/events/dataexport/alerts/securityassessment | Read | x | x | |||
| /api/v2/events/dataexport/alerts/quarantine | Read | x | x | |||
| /api/v2/events/dataexport/alerts/remediation | Read | x | x | |||
| /api/v2/events/dataexport/alerts/policy | Read | x | x | |||
| /api/v2/events/dataexport/alerts/malware | Read | x | x | x | ||
| /api/v2/events/dataexport/alerts/malsite | Read | x | x | x | ||
| /api/v2/events/dataexport/alerts/compromisedcredential | Read | x | x | |||
| /api/v2/events/dataexport/alerts/ctep (or ips) | Read | x | x | |||
| /api/v2/events/dataexport/alerts/dlp | Read | x | x | |||
| /api/v2/events/dataexport/alerts/watchlist | Read | x | x | |||
| /api/v2/policy/urllist/file | Read + Write | |||||
| /api/v2/policy/urllist | Read + Write | x | ||||
| /api/v2/policy/urllist/deploy | Read + Write | x | ||||
| /api/v2/incidents/uba/getuci | Read + Write | x | ||||
| /api/v2/ubadatasvc/user/uci | Read + Write | x | ||||
| /api/v2/services/cci/app | Read | x | ||||
| /api/v2/services/cci/domain | Read | x | ||||
| /api/v2/services/cci/tags | Read | x |
4.2.0 REST API (Deprecated)
Dataexport Error Codes
| Error Codes | User-Action Required | Description |
|---|---|---|
| 403 | Yes | Check the API V2 token is associated with the valid endpoint & its not expired.Retry will solve the problem only after solving the token issue by following these guidelines. |
| 409 | No | Concurrency conflict and the request cannot be processed at this point of time.
DataExport API V2 endpoints do not support downloading the same event type concurrently with the same iterator index, and the Client is expected to validate that the logic to pull the events is single-threaded. |
| 429 | No | Too many requests for the same tenant accessing the same endpoint.
The Client is expected to honor the rate limit to avoid 429 error and as part of the response header, it carries the reset time in the header ratelimit-reset. The Client is expected to sleep/wait ( ratelimit-reset ) to avoid 429. The current rate limit is 4 req / second/endpoint. |
| 5XX | Yes | Netskope is having a temporary server issue for some reason:
Upon receiving a 5xx error from Netskope Server , the User is recommended to do a back off of 5 seconds wait time before the next call. |
v1 REST API Scopes
| Endpoint | Privilege | Log Shipper (CLS) | Ticket Orchestrator (CTO) | Threat Exchange (CTE) | User Risk Exchange (URE) | App Risk Exchange (ARE) | Notes |
|---|---|---|---|---|---|---|---|
| Token Generated and Not Expired | (all) | x | Required for sharing file hashes |
v2 REST API Scopes
Note
Starting with CE 4.2.0, you are required to use the dataexport endpoint permission for the alerts and events you have configured in Cloud Exchange when setting up Netskope Tenants.
| Endpoint | Privilege | Log Shipper (CLS) | Ticket Orchestrator (CTO) | Threat Exchange (CTE) | User Risk Exchange (URE) | App Risk Exchange (ARE) | Notes |
|---|---|---|---|---|---|---|---|
| /api/v2/events/data/alert | Read | ||||||
| /api/v2/events/data/application | Read | ||||||
| /api/v2/events/data/audit | Read | ||||||
| /api/v2/events/data/infrastructure | Read | ||||||
| /api/v2/events/data/network | Read | ||||||
| /api/v2/events/data/page | Read | ||||||
| /api/v2/events/dataexport/events/alert | Read | x | x | x | x | x | Required to validate API token |
| /api/v2/events/dataexport/events/application | Read | x | x | ||||
| /api/v2/events/dataexport/events/audit | Read | x | |||||
| /api/v2/events/dataexport/events/connection | Read | ||||||
| /api/v2/events/dataexport/events/incident | Read | x | |||||
| /api/v2/events/dataexport/events/infrastructure | Read | x | |||||
| /api/v2/events/dataexport/events/network | Read | x | |||||
| /api/v2/events/dataexport/events/page | Read | x | |||||
| /api/v2/events/dataexport/alerts/uba | Read | x | x | ||||
| /api/v2/events/dataexport/alerts/securityassessment | Read | x | x | ||||
| /api/v2/events/dataexport/alerts/quarantine | Read | x | x | x | |||
| /api/v2/events/dataexport/alerts/remediation | Read | x | x | ||||
| /api/v2/events/dataexport/alerts/policy | Read | x | x | ||||
| /api/v2/events/dataexport/alerts/malware | Read | x | x | x | |||
| /api/v2/events/dataexport/alerts/malsite | Read | x | x | x | |||
| /api/v2/events/dataexport/alerts/compromisedcredential | Read | x | x | ||||
| /api/v2/events/dataexport/alerts/ctep (or ips) | Read | x | x | ||||
| /api/v2/events/dataexport/alerts/dlp | Read | x | x | ||||
| /api/v2/events/dataexport/alerts/watchlist | Read | x | x | ||||
| /api/v2/policy/urllist/file | Read + Write | ||||||
| /api/v2/policy/urllist | Read + Write | x | |||||
| /api/v2/policy/urllist/deploy | Read + Write | x | |||||
| /api/v2/incidents/uba/getuci | Read + Write | x | |||||
| /api/v2/ubadatasvc/user/uci | Read + Write | x | |||||
| /api/v2/services/cci/app | Read | x | |||||
| /api/v2/services/cci/domain | Read | x | |||||
| /api/v2/services/cci/tags | Read | x |
x: Required API scopes for the corresponding CE module.