Purpose
Purpose
Connect Netskope to AirMDR using your Tenant URL and API Token to enable supported security investigations and automated workflows.
Supported Versions
Supported Versions
Authentication
Authentication
Netskope-Api-Token: <generated-api-token>Netskope documents this header for REST API v2 requests.Bearer prefix.- RBAC V3: A Tenant Admin manages administrators and roles. Assign the integration service account a role containing only the required permissions. Netskope Administrators RBAC V3
- Legacy workflow: Configure access for individual endpoints when creating the token.
- Grant read access for retrieval operations. Grant write access only where a supported skill changes Netskope data or configuration.
Pre-requisites
An active Netskope tenant with access to the required API features.Netskope administrator access to create API credentials and assign permissions.
Setup Steps
Retrieve the Tenant URL
- Open your organization’s Netskope administration console.
- Sign in with your administrator account.
- After authentication completes, select the browser address bar.
- Copy the HTTPS scheme and tenant hostname.
- Remove any page path, query parameters, or fragment.
For example: - Retain the exact hostname assigned to your tenant.
Netskope assigns the Tenant URL when provisioning the tenant. You retrieve this value; you do not generate it. Do not append
/api/v2, a login path, or an API endpoint to the AirMDR Tenant URL field.
Generate an API Token
Generate an API Token — RBAC V3
RBAC V3 — Service Account
Use this procedure when your tenant provides the Service Account option.- Open Settings → Administration → Administrators & Roles.
-
Ensure an appropriate integration role exists with the permissions required by the AirMDR skills. If not create a dedicated role.
How to create a Dedicated Role in Netskope — RBAC V3 ?
Create a role to define the permissions available to the AirMDR service account.Sign in to Netskope with the predefined Tenant Admin role.- Navigate to Settings → Administration > Administrators & Roles.
- Select the Roles tab.
- Click New.
- Enter the role details:
- Select the functional areas required by the AirMDR skills you intend to use.
- Review the functions and permissions displayed below the selected areas. Netskope automatically selects associated permissions; adjust them to retain only the required access and dependencies.
- Click the information icon beside a permission set to check its associated API endpoints. Confirm that it includes the methods and endpoints required by your skills.
- If applicable, configure Scope and Obfuscation to control which records and fields the integration can access.
- If your organization requires IP restrictions, open IP Allowlist and add the approved outbound IP addresses used by AirMDR or its Remote Agent.
- Click Save.
- Confirm that
AirMDR-Integration-Roleappears in the Roles list.
Required Permissions for Skills
- Select the Administrators tab.
- Click Service Account.
-
Enter a descriptive service account name, such as:
AirMDR-Integration-Role - Select the approved role from the Role dropdown.
- Configure REST API token generation and enter the expiration period in days.
- Leave the option to generate the token later unselected.
- Click Create.
- Copy the generated API token immediately and store it in an approved secrets manager.
Generate an API Token — Legacy Workflow
Legacy — REST API v2
Use this procedure only when token creation remains available under REST API v2.- Open Settings > Tools > REST API v2.
- Check REST API Status.
- If disabled, click the pencil icon, enable REST API access, and click Save.
- Click New Token.
- Enter a token name, such as
AirMDR-Integration. - Select an expiration period aligned with your organization’s credential policy.
- Click Add Endpoint.
- Select the endpoints confirmed for the AirMDR integration.
- Assign the required privileges to each endpoint:
- Read for supported retrieval operations.
- Read + Write where modification operations are required.
- Click Save.
- On the confirmation page, click Copy Token.
- Store the token securely, then click OK.
Netskope Credential Reference Table
Bearer, Netskope-Api-Token:, or quotation marks in the API Token field.Validate Connectivity
Use a read-only endpoint that the token is permitted to access. The example below queries alert records through Netskope’s Datasearch API.GET /api/v2/events/datasearch/alert. Permission for a Dataexport endpoint does not automatically establish permission for this endpoint.- Open a Bash terminal on an approved system.
- Run the following commands, replacing the example Tenant URL:
Request Sample
- Confirm that the HTTP status is
200and the response reportsstatus.executionasSUCCESS.Illustrative successful response when no records match:
- Review any error message before retrying.
Configure Netskope in AirMDR Integrations Dashboard
- Navigate to AirMDR, provide the credentials and click Login
- Navigate to the AirMDR Integrations Dashboard in the left navigation pane and select ADMIN → Integrations.
- Use the search option, enter the keyword “Netskope”, select the Connections tab, and click + New Connection button.
-
Use the following values in the AirMDR integration configuration screen:
Expand Advanced Configuration if required. (Optional)
- In Remote Agent, select an AirMDR Remote Agent when access to your Netskope tenant requires an approved proxy or controlled outbound network route. If Netskope IP allowlisting is enabled, ensure the selected runtime’s outbound IP address is permitted. Otherwise, leave this field unselected unless instructed by your AirMDR administrator.
- In Expiry, select the date on which AirMDR should treat the stored Netskope credentials as expired, according to your organization’s credential-rotation policy. Set this date no later than the API token’s expiration in Netskope.
The Expiry setting in AirMDR does not extend, rotate, or revoke the Netskope API token. Before the token expires, generate a replacement using the applicable Netskope token-generation method, update the API Token in AirMDR, and validate the connection. Revoke the previous token after confirming that all integrations using it have been updated. - Click Save.
Skills provided by this Integration
The Netskope integration provides investigation, device and application assessment, policy review, and event retrieval skills to help security teams investigate activity, assess potential impact, and review Netskope security information.Investigation Skills
Investigation Skills
GetUserDetails operation is part of the User Management API and returns user status and device details.Device and Application Assessment Skills
Device and Application Assessment Skills
Policy Review Skills
Policy Review Skills
Event Retrieval Skills
Event Retrieval Skills
Required Permission Summary
Additional Information
🛑 Security & Access Best Practices
🛑 Security & Access Best Practices
- Use a dedicated service account for AirMDR when your tenant supports RBAC V3.
- Grant only the endpoint and role permissions required by the enabled skills.
- Use the Tenant URL and API Token from the same Netskope tenant.
- Store the API token in an approved secrets manager and restrict access to authorized administrators.
- Use HTTPS and keep TLS certificate validation enabled.
- If IP allowlisting is enabled, permit the approved outbound IP addresses used by AirMDR or the selected Remote Agent.
- Track token expiration and rotate credentials according to your organization’s security policy.
- During routine rotation, update the token in AirMDR and validate the connection before revoking the previous token.
- Review integration failures, role changes, and access to sensitive DLP forensic information.
- Revoke exposed tokens promptly and replace them in affected connections.
- Do not share API tokens through email, Slack, or support tickets.
- Do not expose tokens in screenshots, logs, source-control repositories, or configuration examples.
- Do not assign Tenant Admin or broad write permissions unless explicitly required and verified.
- Do not assume access to one event endpoint permits access to every event type.
- Do not use an example Tenant URL without replacing it with your actual tenant address.
- Do not send the API token in URL query parameters.
- Do not disable TLS verification to bypass connection errors.
- Do not assume the Expiry field in AirMDR extends, rotates, or revokes the token in Netskope.
- Do not retain unused tokens or service accounts after the integration is retired.
👉 Support & Maintenance
👉 Support & Maintenance
- 📧 Contact AirMDR Support through your designated support channel.
- 🔁 Rotate credentials regularly. Recommended cadence: As per internal security policy
-
🔄 Reconnect in AirMDR immediately when API Keys are changed.
Revoke the previous credential after confirming all consumers have migrated.Legacy tokens retained after RBAC V3 activation continue until expiration but cannot be extended. Plan migration before they expire.
- Use the Netskope Support portal for tenant access, API availability, or token provisioning issues.
🛑 Data Flow & Security
🛑 Data Flow & Security
- An AirMDR skill initiates a request to the configured Netskope tenant.
- Netskope evaluates the supplied token and its associated permissions.
- Netskope returns the requested data or operation result.
- AirMDR uses the response in the calling workflow.
🔄 Monitoring & Logs
🔄 Monitoring & Logs
🧰 Error Handling
🧰 Error Handling

