Skip to main content
To connect Orca Security to AirMDR using your regional API URL and an API token. This guide explains how to obtain the credentials, create the AirMDR connection, configure Remote Agent and Expiry, and troubleshoot common issues.The data and operations available through the connection depend on:
  • The Orca skills enabled in AirMDR.
  • The permissions assigned to the API token.
  • The accounts and resources included in the token’s scope.
  • The API capabilities available to your Orca tenant.
Connection VerificationWhen you save an Orca Security connection, AirMDR verifies authentication by sending POST /api/serving-layer/query to query the Alert model with a limit of one alert.The token must have Serving Layer alert-read access even when the connection will be used only for write skills. A token that permits write actions but lacks this read access will fail connection verification.Successful verification confirms access to the alert-query operation. It does not confirm permission to add comments, snooze alerts, change their status, or update their scores. Validate each write skill required by your workflows separately.API token authenticationCreate an API token in Orca and enter its value in the AirMDR connection.Orca publishes token-based authentication examples using this header:
The Token prefix is part of the request header. Enter only the generated secret value in AirMDR’s API Token field unless its field instructions explicitly request a complete header. 
Assign a role that grants Serving Layer alert-read access for connection verification and alert retrieval. For alert-management workflows, also grant access to the bulk-action endpoints required by the selected skills. Restrict the token’s resource scope to the accounts and resources required for those workflows.

Pre-requisites

An active Orca Security tenant with API access.
An Orca user authorized to create and manage API tokens.
Confirmation of the region hosting your Orca tenant.
Permission to create an API token and permission to access data through that token are separate requirements.

Setup Steps

1

Sign in to the correct Orca region

  1. Open the Orca Security region-selection page.
  2. Select the region in which your organization’s Orca tenant is hosted.
  3. Sign in using your organization’s approved authentication method.
  4. Confirm that you are accessing the correct organization before creating the token.
    Select the tenant’s hosting region. Your physical location does not determine the tenant region.
2

Identify the API URL

The API URL is an existing regional endpoint; it is not generated when you create a token.
  1. Confirm the hosting region selected during sign-in.
  2. Open Settings → Users & Permissions → API.
  3. Use any API documentation or endpoint information available to your tenant to confirm the regional API base URL.
  4. If the endpoint is not displayed, obtain it from your Orca administrator or Orca Support.
  5. Record the confirmed URL for the AirMDR connection.
Use the following regional API URLs as a reference and confirm the applicable host for your tenant.
When entering the URL:
  • Use https://.
  • Do not enter the region-selection URL or a dashboard page.
  • Do not append an individual resource endpoint.
  • Enter the regional HTTPS host only, without /api/, a resource endpoint, query parameters, or any other path. AirMDR automatically appends the API path when sending requests.
3

Open API token management

  1. In Orca, select Settings.
  2. Under Users & Permissions, select API.
  3. Select Add API Token. Some documented UI versions label this action Create API Token.
    If the API page or token-creation action is unavailable, ask your Orca administrator to review your access.
4

Configure the token

Complete the fields displayed in the token dialog.Example values:
A narrowly scoped token can authenticate successfully while returning only part of the organization’s data.
5

Generate and securely copy the token

  1. Review the role, scope, and expiration settings.
  2. Click Add.
  3. In the generated-token window, copy the token before selecting Continue.
  4. Store it temporarily in an approved password manager or secret-management system.
  5. Record its expiration date separately.
The Orca Security token may be visible only once.
If it is lost, generate a new token and update the AirMDR integration.
Do not include the token in screenshots, email, chat, Jira tickets, or documentation examples.

Orca Security Credential Reference Table

Copy the generated Orca token before closing the token window; the published workflow states that it cannot be retrieved again after continuing.

Validate Connectivity

You can optionally validate the Orca API URL and token before adding them to AirMDR. The following request queries up to one open alert through the Serving Layer API. Although it uses POST, it retrieves information without changing alerts. The endpoint uses Authorization: Token <API_TOKEN>. 
Prerequisite: The token must have alert-read permission and access to the required accounts or business units.
Replace <ORCA_API_TOKEN> with your generated token. The example uses the default US API host; replace it with your confirmed regional host when applicable.This example adapts the published Serving Layer alert-query format by limiting the result to one record.
A manual cURL request includes the complete endpoint path. The AirMDR API URL field contains only the host because AirMDR appends that path.
A successful request should return **HTTP **200 OK and a JSON response. Review the response body for any application-level error.
This test validates alert retrieval from the machine running the command. Validate the AirMDR connection separately, and test status changes, snoozing, comments, and score updates to confirm their write permissions.

Configure Orca Security in AirMDR Integrations Dashboard

  1. Navigate to AirMDR, provide the credentials and click Login
  2. Navigate to the AirMDR Integrations Dashboard in the left navigation pane and select ADMIN → Integrations.
  3. Use the search option, enter the keyword “Orca Security”, select the Connections tab, and click + New Connection button.
  4. Use the following values in the AirMDR integration configuration screen:
    1. In Remote Agent, select an AirMDR Remote Agent when Orca API requests must run through an approved network route. Ensure the selected agent can resolve and reach the regional Orca API host over HTTPS. For direct connectivity from AirMDR, leave this field unselected.
    2. In Expiry, select the Orca token’s expiration date or an earlier date required by your organization’s credential-rotation policy.
    Expiry controls credential validity in AirMDR. It does not automatically rotate, extend, or revoke the token in Orca Security. Create a replacement token, update API Token and Expiry, save and validate the connection, and then revoke the previous token when it is no longer required.
  5. Click Save.
    AirMDR verifies the connection using a Serving Layer alert query. If verification fails, review the token’s validity, alert-read access, resource scope, and connectivity to the configured API host.

Skills provided by this Integration

Changing an alert’s status, snooze period, or score manages the alert record. It does not demonstrate that the underlying cloud risk has been remediated.
To view the details of Input Parameters and Output for the respective skills

Permissions and Roles by Skill

All connections require Serving Layer alert-read access for authentication verification. Grant additional bulk-action access only for the write skills your workflows use. The token must also include the target alerts within its resource scope.
Although the four write skills use Orca bulk-action endpoints, each request is restricted to one alert by a sonar_filter on AlertId. The token therefore needs access to the corresponding bulk action even when the skill modifies only one alert.Enter only the regional HTTPS host in AirMDR’s API URL field. AirMDR appends the endpoint path.
Assign the API token access to the cloud accounts or business units containing the alerts that AirMDR will retrieve or manage. Orca’s token configuration supports resource scoping.
Important: The user creating the token needs token-management privileges. The integration token itself should receive only the operational permissions above; administrator access is not established as a requirement for these skills.

Additional Information

The following describes common HTTP and connection symptoms. The returned error details should guide the final diagnosis.
Do not repeatedly retry authentication or permission failures without correcting their cause.
Review execution results in AirMDR
  1. Open the playbook or skill execution that used the Orca connection.
  2. Review its status, inputs, outputs, and error details.
  3. Identify whether the failure concerns connectivity, authentication, authorization, or request parameters.
  4. Record the execution ID and timestamp for troubleshooting.
Use the execution-history controls available in your AirMDR environment.Review the token in Orca
  1. Navigate to Settings → Users & Permissions → API.
  2. Locate the integration token.
  3. Review its expiration, role, and resource scope.
  4. Check relevant audit information if it is available to your tenant.
Recommended diagnostic informationRecord:
  • Connection name.
  • Execution ID and timestamp.
  • API host and requested operation.
  • HTTP status code and sanitized error.
  • Remote Agent identity, when applicable.
Do not record authorization headers or token values.Illustrative log entriesThese examples show useful diagnostic fields; they are not the native AirMDR or Orca log format.
Use INFO for routine operation and WARN/ERROR for failures. Enable DEBUG temporarily only when needed, with secrets and sensitive response data redacted.
✅ Do
  • Create a dedicated token for the AirMDR connection.
  • Grant only the permissions required by enabled skills.
  • Restrict access to the necessary resources.
  • Use an approved expiration date and rotate credentials in advance.
  • Confirm the regional endpoint before entering credentials.
  • Keep TLS certificate validation enabled.
  • Store credentials in approved secret-management systems.
  • Mask secrets in screenshots, recordings, and support evidence.
❌ Don’t
  • Sharing tokens through email, chat, or tickets.
  • Granting administrator access as a general troubleshooting measure.
  • Using non-expiring tokens without policy approval.
  • Entering a dashboard or region-selection URL as the API URL.
  • Assuming every regional API host follows the same naming pattern.
  • Assuming AirMDR Expiry changes the token in Orca.
  • Assuming a Remote Agent expands the token’s access.
  • 📧 Contact AirMDR Support through your designated support channel.
  • 🔁 Rotate credentials regularly. Recommended cadence: As per your internal security policy
  • 🔄 Replace a token before expiration
    1. Create a replacement token in Orca with the approved role and scope.
    2. Copy and securely store the new value.
    3. Edit the existing Orca connection in AirMDR.
    4. Replace API Token.
    5. Update Expiry.
    6. Save and validate a read-only skill.
    7. After successful validation, revoke or delete the previous token in Orca using the available token-management controls.
    8. Update the credential inventory and remove obsolete secret copies.
      If compromise is suspected, revoke the affected token promptly and follow your incident-response process.
Data exchangedAirMDR retrieves Orca alerts through the Serving Layer API when using Fetch Orca Security Alerts Version 2. The legacy Version 1 skill retrieves alerts through GET /api/alerts.The alert-management skills add comments, snooze alerts, change alert status, or update alert scores through Orca bulk-action endpoints. Each write request targets one alert using a sonar_filter on AlertId.Requests run directly from AirMDR or through the configured AirMDR Remote Agent. Remote Agent execution is supported for all Orca connector calls.Connection flowMermaid Diagram 2Network and security requirements
HTTPS protects traffic in transit. Specific encryption-at-rest algorithms, retention periods, and regional-storage guarantees must be taken from the applicable vendor security documentation.