> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airmdr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Orca Security

> The Orca Security integration enables AirMDR to access Orca data through supported integration skills. Security teams can use the available skills to add cloud-security context to investigations and automate applicable playbook tasks.

> [accordion] Purpose
>
> 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.

> [accordion] Supported Versions
>
> | Component | Compatibility requirement |
> | - | - |
> | Orca Security | Cloud-hosted Orca tenant with access to the APIs required by the selected AirMDR skills |
> | Orca API | Endpoints supported by the deployed AirMDR Orca connector |
> | AirMDR | Environment in which the Orca Security integration is available |
> | Authentication | Orca API token |
> | Network connection | HTTPS to the applicable regional API endpoint |

> [accordion] Authentication
>
> **Connection Verification**
>
> When 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 authentication**
>
> Create an API token in Orca and enter its value in the AirMDR connection.
>
> Orca publishes token-based authentication examples using this header:
>
> ```text theme={null}
> Authorization: Token <ORCA_API_TOKEN>
> ```
>
> 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. 
>
> > [accordion] Role-based access considerations
> >
> > 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

> > [!TIP]
> >
> > An active Orca Security tenant with API access.
>
> > [!TIP]
> >
> > An Orca user authorized to create and manage API tokens.
>
> > [!TIP]
> >
> > Confirmation of the region hosting your Orca tenant.
>
> > [!TIP]
> >
> > 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](https://region-selection.orcasecurity.io/).
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.
   > [!NOTE]
   >
   > 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.

| Tenant region | API URL — host only |
| - | - |
| United States | `https://app.us.orcasecurity.io` |
| Europe | `https://app.eu.orcasecurity.io` |
| Australia | `https://app.au.orcasecurity.io` |
| India | `https://app.in.orcasecurity.io` |
| Israel | `https://api.il.orcasecurity.io` |
| Brazil | `https://api.sa.orcasecurity.io` |

> [!TIP]
>
> 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**.
   > [!NOTE]
   >
   > 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.

| Field | What to configure |
| :- | :- |
| **Name** | A descriptive name, such as `AirMDR-Production` |
| **Description** | The integration purpose and owner |
| **Never Expire** | Leave unselected when your policy requires time-limited credentials |
| **Expiration** | An approved expiry date |
| **Service Token** | Select when an organizational service token is appropriate and permitted |
| **Role** | The role required for the selected AirMDR operations |
| **Scope access to specific resources** | Restrict access to the necessary accounts, business units, or projects, where available |

Example values:

```text theme={null}
Name: AirMDR-Production
Description: Orca integration for approved AirMDR investigation workflows
Role: A role granting alert-read access and the bulk-action access required by your selected skills
Expiration: Date approved by the organization
Scope: Required production accounts or business units
```

> [!NOTE]
>
> 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.

> [!WARNING]
>
> **The Orca Security token may be visible only once.** \
> **If it is lost, generate a new token and update the AirMDR integration.**

> [!WARNING]
>
> **Do not include the token in screenshots, email, chat, Jira tickets, or documentation examples.**

### Orca Security Credential Reference Table

| Credential / Field | Required | Where to obtain | Description |
| :- | :- | :- | :- |
| **API URL** | Yes | Orca tenant API documentation or your Orca administrator | Regional HTTPS host used to connect to Orca Security. Enter the host only, without `/api/` or any other path. AirMDR appends the API path automatically. |
| **API Token** | Yes | Orca Security → **Settings → Users & Permissions → API → Add API Token / Create API Token** | Token used to authenticate API requests. Enter only the generated token value, without the `Token` prefix. Assign the access required by the selected skills. |

> [!WARNING]
>
> 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>`. 

> [!TIP]
>
> **Prerequisite:** The token must have alert-read permission and access to the required accounts or business units.

> [accordion] Sample Request
>
> 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.
>
> > [!NOTE]
> >
> > A manual cURL request includes the complete endpoint path. The AirMDR **API URL** field contains only the host because AirMDR appends that path.
>
> ```text theme={null}
> curl --request POST \
>   --url 'https://app.us.orcasecurity.io/api/serving-layer/query' \
>   --header 'Authorization: Token <ORCA_API_TOKEN>' \
>   --header 'Content-Type: application/json' \
>   --header 'Accept: application/json' \
>   --connect-timeout 10 \
>   --max-time 30 \
>   --include \
>   --data '{
>     "query": {
>       "models": ["Alert"],
>       "type": "object_set",
>       "with": {
>         "operator": "and",
>         "type": "operation",
>         "values": [
>           {
>             "key": "Status",
>             "operator": "in",
>             "type": "str",
>             "values": ["open"]
>           }
>         ]
>       }
>     },
>     "select": [
>       "AlertId",
>       "Title",
>       "Status",
>       "OrcaScore"
>     ],
>     "limit": 1,
>     "start_at_index": 0
>   }'
> ```

> [accordion] Sample Response
>
> A successful request should return \*\*HTTP \*\*`200 OK` and a JSON response. Review the response body for any application-level error.
>
> ```http theme={null}
> HTTP/2 200
> content-type: application/json
> ```

> [accordion] Troubleshooting
>
> | Result | What to check |
> | - | - |
> | `400 Bad Request` | Query format and field names |
> | `401 Unauthorized` | Token value, expiration, or revocation |
> | `403 Forbidden` | Alert-read permission and resource scope |
> | `404 Not Found` | Regional host and endpoint path |
> | `429 Too Many Requests` | Request frequency and retry guidance |
> | Timeout or TLS error | DNS, firewall, proxy, and certificate trust |
>
> > [!NOTE]
> >
> > 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](https://app.airmdr.com/auth/login), 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:

   | AirMDR field | What to enter | Example |
   | :- | :- | :- |
   | **Instance** | A unique connection name | `Orca-Security-Production` |
   | **Organization**, if displayed | The AirMDR organization owning the connection | Select the appropriate organization |
   | **Description**, if displayed | A brief connection purpose | `Production Orca investigation connection` |
   | **API URL** | Regional HTTPS host only, without `/api/` or any other path | `https://app.us.orcasecurity.io` |
   | **API Token** | The generated token value | `<ORCA_API_TOKEN>` |

   > [accordion] Expand Advanced Configuration if required. (Optional)
   >
   > 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.
   >
   > > [!NOTE]
   > >
   > > 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**.
   > [!NOTE]
   >
   > 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

> [accordion] Alert Investigation
>
> | Skill | Purpose | Access type | Required permission |
> | :- | :- | :- | :- |
> | **Fetch Orca Security Alerts** | Retrieves alerts through the Serving Layer API. Supports filters including alert ID, type, category, risk level, status, source, minimum Orca score, and a relative time window. | Read | Alert-read access through the Serving Layer API for the required resources. |

> [accordion] Alert Lifecycle Management
>
> | Skill | Purpose | Access type | Required permission |
> | :- | :- | :- | :- |
> | **Update Orca Security Alert Status** | Changes the status of a single alert. Accepts `open`, `in_progress`, `dismiss`, `dismissed`, `close`, or `closed`, with optional `reason` and `justification`. | Write | Alert-read access for connection verification and access to the bulk status-change endpoint for the requested action. |
> | **Snooze Orca Security Alert** | Snoozes a single alert for a specified number of days, with optional `reason` and `justification`. The alert reappears when the snooze period expires. | Write | Alert-read access for connection verification and access to the bulk snooze endpoint. |
> | **Update Orca Security Alert Score** | Updates a single alert using `score` as an integer with no range limit imposed by the skill, `orca_score` as a floating-point value from `0` to `10` inclusive, or both, with optional `reason` and `justification`. | Write | Alert-read access for connection verification and access to the bulk score-change endpoint. |
>
> > [!NOTE]
> >
> > 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.

> [accordion] Investigation Notes and Evidence
>
> | Skill | Purpose | Access type | Required permission |
> | :- | :- | :- | :- |
> | **Add Comment to Orca Security Alert** | Adds a comment to a single alert identified by `AlertId` to record investigation notes, triage findings, or remediation evidence. | Write | Alert-read access for connection verification and access to the bulk comment endpoint. |

> [!TIP]
>
> To view the details of Input Parameters and Output for the respective skills
>
> * Go to [AirMDR → Orca Security](https://app.airmdr.com/integrationsv2/4ec06f1a-09f2-40c0-89cf-831682ecc587/skills?search=orca) Integration page.
> * Select the **Skills** tab and click on the required listed skills.

### Permissions and Roles by Skill

| AirMDR skill | Required access | Applicable role | Required permissions |
| - | - | - | - |
| Fetch Orca Security Alerts — Version 2 | Query and retrieve alerts through the Serving Layer API. | An Orca role granting alert-read access. | Permission to retrieve alerts through `POST /api/serving-layer/query`, within the token’s resource scope. |
| Fetch Orca Security Alerts — Version 1 | Retrieve alerts through the legacy alerts endpoint. | An Orca role granting legacy alert-read access. | Permission to retrieve alerts through `GET /api/alerts`. Saving the connection also requires Serving Layer alert-read access. |
| Update Orca Security Alert Status | Change the status of the target alert. | An Orca role granting alert-read access and bulk status-change access. | Serving Layer alert-read access and permission to execute `PUT /api/alerts/bulk/status/{status}` for the requested status action. |
| Snooze Orca Security Alert | Snooze the target alert. | An Orca role granting alert-read access and bulk snooze access. | Serving Layer alert-read access and permission to execute `PUT /api/alerts/bulk/snooze`. |
| Add Comment to Orca Security Alert | Add a comment to the target alert. | An Orca role granting alert-read access and bulk comment access. | Serving Layer alert-read access and permission to execute `PUT /api/alerts/bulk/comment`. |
| Update Orca Security Alert Score | Update the target alert’s score. | An Orca role granting alert-read access and bulk score-change access. | Serving Layer alert-read access and permission to execute `PUT /api/alerts/bulk/score_change`. |

> [!NOTE]
>
> 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.

> [accordion] API Endpoints Used by AirMDR
>
> | Operation | HTTP method | API path | Behavior |
> | - | - | - | - |
> | Verify Authentication | `POST` | `/api/serving-layer/query` | Queries the `Alert` model with a limit of one alert when the connection is saved. |
> | Fetch Orca Security Alerts — Version 2 | `POST` | `/api/serving-layer/query` | Retrieves alerts using Serving Layer queries. |
> | Fetch Orca Security Alerts — Version 1 | `GET` | `/api/alerts` | Retrieves alerts using the legacy endpoint deprecated by Orca. |
> | Add Comment to Orca Security Alert | `PUT` | `/api/alerts/bulk/comment` | Adds a comment to the selected alert. |
> | Snooze Orca Security Alert | `PUT` | `/api/alerts/bulk/snooze` | Snoozes the selected alert. |
> | Update Orca Security Alert Status | `PUT` | `/api/alerts/bulk/status/{status}` | Changes the selected alert’s status. |
> | Update Orca Security Alert Score | `PUT` | `/api/alerts/bulk/score_change` | Updates the selected alert’s score. |
>
> > [!NOTE]
> >
> > 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.

> [accordion] Recommended Configuration for All Five Skills
>
> Create a custom role named, for example, **AirMDR Orca Alert Management**, with:
>
> * Alert-read access.
> * Alert status-change access.
> * Alert closing/verifying access.
> * Alert snooze access.
> * Alert score-update access.
> * Alert comment-creation access, once its permission mapping is confirmed.
>
> If your tenant exposes a broader **Alerts Write** permission instead of separate action controls, validate it against all four write skills. It is a candidate configuration, **not a confirmed minimum permission set**.

> [accordion] Resource Scope
>
> 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.
>
> | Setting | Requirement |
> | :- | :- |
> | **Role / Permissions** | Allows the required read or write operation |
> | **Resource Scope** | Allows access to the account or business unit associated with the alert |
>
> > **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

> [accordion] 🧰 Error Handling
>
> The following describes common HTTP and connection symptoms. The returned error details should guide the final diagnosis.
>
> | Symptom | Possible cause | Recovery steps |
> | - | - | - |
> | Cannot access API token settings | Insufficient Orca permissions | Ask the administrator to review token-management access |
> | Required AirMDR field rejected | Missing value or incorrect URL format | Check the connector’s field instructions |
> | `400 Bad Request` | Invalid input, query, or request format | Review the skill inputs and endpoint requirements |
> | `401 Unauthorized` | Incorrect, expired, or revoked token | Verify token validity and replace the stored value when necessary |
> | `403 Forbidden` | Missing permission or restricted resource access | Review the role, scope, and any applicable access policy |
> | `404 Not Found` | Incorrect host/path or unavailable endpoint | Confirm the regional URL and check for a duplicated `/api/` path |
> | `429 Too Many Requests` | Request rate exceeded | Reduce concurrency and follow any supplied retry guidance |
> | `5xx` response | Service-side or upstream failure | Check availability and retry with a bounded delay |
> | DNS or connection timeout | DNS, firewall, proxy, or routing issue | Test from the actual AirMDR execution route |
> | TLS certificate error | Certificate trust or proxy inspection issue | Correct the trust configuration; retain certificate validation |
> | Successful request with missing data | Scope restrictions, filters, or unavailable records | Check the token’s resource scope and skill inputs |
> | Remote Agent execution fails | Agent unavailable or unable to reach Orca | Check agent health and outbound connectivity |
> | Connection credentials marked expired | AirMDR Expiry reached | Replace or verify the credentials and update Expiry appropriately |
>
> > [!NOTE]
> >
> > Do not repeatedly retry authentication or permission failures without correcting their cause.

> [accordion] 🔄 Monitoring & Logs
>
> **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 information**
>
> Record:
>
> * 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 entries**
>
> These examples show useful diagnostic fields; they are not the native AirMDR or Orca log format.
>
> ```text theme={null}
> INFO integration=orca_security connection=Orca-Security-Production
> operation=read_only_query http_status=200 result=success
>
> ERROR integration=orca_security connection=Orca-Security-Production
> operation=read_only_query http_status=401 result=authentication_failed
> ```
>
> Use **INFO** for routine operation and **WARN/ERROR** for failures. Enable **DEBUG** temporarily only when needed, with secrets and sensitive response data redacted.

> [accordion] 🛑 Security & Access Best Practices
>
> **✅ 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.

> [accordion] 👉 Support & Maintenance
>
> * 📧 Contact [**AirMDR Support**](mailto:support@airmdr.com) 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.
>      > [!WARNING]
>      >
>      > If compromise is suspected, revoke the affected token promptly and follow your incident-response process.

> [accordion] 🛑 Data Flow & Security
>
> **Data exchanged**
>
> AirMDR 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 flow**
>
> ![Mermaid Diagram 2](https://mintcdn.com/airmdr/1FGkbbt5A_OPbw8d/images/mermaid-diagram-2.png?fit=max\&auto=format\&n=1FGkbbt5A_OPbw8d\&q=85\&s=199303fe896befb7544baad364d67594)
>
> **Network and security requirements**
>
> | Area | Requirement |
> | :- | :- |
> | Transport | Use HTTPS with certificate validation |
> | Destination | Confirmed regional Orca API hostname |
> | API port | TCP 443 for standard HTTPS endpoints |
> | Request authentication | API token in the authorization header |
> | Resource access | Restricted by the token’s role and scope |
> | Network allowlisting | Permit the required destination from the actual execution environment |
> | Credentials and retained results | Follow the applicable AirMDR, Orca, and organizational storage controls |
>
> > [!NOTE]
> >
> > 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.