> ## 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.
# Material Security
> The Material Security integration enables AirMDR to authenticate with a Material Security tenant and execute supported Material Security API operations through AirMDR skills and playbooks.
The Material Security integration connects AirMDR with a Material Security tenant, enabling AirMDR skills and playbooks to securely access and process supported Material Security data. The connection is established using the tenant-specific **Base URL** and an **API Token** generated in the Material Security UI.
The connection uses:
* A tenant-specific **Base URL**
* An **API Token** generated in the Material Security UI
| Component | Supported interface | Details |
| :---------------- | :------------------------------------ | :-------------------------------------------------- |
| Material Security | Material API v1 | Uses tenant-specific API endpoints. |
| AirMDR | Current Material Security integration | Requires the **API Token** and **Base URL**. |
| Authentication | Token-based authentication | Uses the `x-material-client-secret` request header. |
| Network protocol | HTTPS | Uses TCP port `443`. |
Material API v1 endpoints follow this format: `https://.on.material.security/api/v1/`
Material Security continues to provide its beta API. However, new API improvements focus on API v1. Confirm which API version is used by each AirMDR Material Security skill.
Material Security uses token-based authentication.
AirMDR sends the API token in the following request header: x-material-client-secret: \
Each API token is associated with a specific Material Security account.
The token identifies the account making the request but does not provide permissions independently. Material Security evaluates each API request against the account’s current permissions.
Therefore, changes to the account’s role or permissions also affect its existing API tokens.
* Use a dedicated service account for the AirMDR integration.
* Assign only the permissions required by the AirMDR skills.
* Avoid using a Super Admin or Tenant Admin account for routine integration activities.
* Any role can create an API token for its own account unless token creation has been disabled.
* Only Super Admins and Tenant Admins can create or modify tokens for other accounts.
* Review service-account permissions periodically.
Treat the API token like a password. Do not include it in documentation, screenshots, support tickets, source code, scripts, or public repositories.
### Pre-requisites
>
> An active Material Security tenant and access to **Integrations → API → Tokens** in Material Security.
>
>
>
> A dedicated Material Security service account with the required permissions.
>
Any Material Security role can create an API token for its own account. Only a **Super Admin** or **Tenant Admin** can create or modify tokens for another account.
For production environments, create the token using a dedicated service account. Material Security does not recommend generating production tokens for Super Admin or Tenant Admin accounts.
## Setup Steps
1. Sign in to the Material Security UI.
2. In the browser address bar, identify your tenant URL.
The URL follows this format: https\://\.[on.material.security](http://on.material.security)
3. Copy only the protocol and hostname.
4. Remove any:
* Page path
* Query parameters
* URL fragment
* Trailing slash
**Example**: Material Security browser URL:
[https://acme.on.material.security/integrations/api/tokens](https://acme.on.material.security/integrations/api/tokens)
Enter the following value in the AirMDR **Base URL** field:
[https://acme.on.material.security](https://acme.on.material.security)
Do not include the Material Security UI page path.
Do not append `/api/v1` to the AirMDR Base URL unless the AirMDR connector implementation explicitly requires it. Material Security API examples construct endpoint URLs by appending `/api/v1/...` to the tenant origin.
1. Sign in to Material Security using the dedicated service account.
2. From the top toolbar, select **Integrations**.
3. Navigate to **API → Tokens**.
4. On the **API Tokens** page, select **Create Token**.
5. Enter a descriptive name that identifies the integration, environment, and purpose for the token.
For example: `AirMDR-Production-Integration`.
6. Select the generated token box to copy the token to the clipboard.
7. Store the token in an approved secrets manager until it is configured in AirMDR.
Do not capture the generated token in screenshots.
Do not send the API token through email, Slack, Jira, or another unapproved communication channel.
### Material Security Credential Reference Table
| AirMDR Field | What to Enter | Where to Get It in the Material Security UI | Example |
| ------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| **API Token** | API token generated for the dedicated Material Security service account. | Go to **Integrations** (puzzle icon) > **API** > **Tokens** > **Create Token**. Enter a descriptive name, create the token, and copy it. | `` |
| **Base URL** | Material Security tenant URL containing only the protocol and hostname. Do not include UI paths or `/api/v1`. | Sign in to Material Security and copy the tenant origin from the browser address bar. | `https://acme.on.material.security` |
Store the API token securely and do not include it in screenshots, documentation, logs, or support tickets.
### Validate Connectivity
Use the following request to confirm that the tenant domain and API key can access the API:
```json theme={null}
curl --request GET \
--url "${MATERIAL_BASE_URL}/api/v1/issues?status=open&limit=1" \
--header "x-material-client-secret: ${MATERIAL_API_TOKEN}"
```
```json theme={null}
\{
"meta": \{
"totalCount": 1,
"limit": 1,
"hasMore": false,
"nextCursor": null
\},
"items": [
\{
"id": "example-issue-id",
"name": "Example security issue",
"status": "open"
\}
]
\}
```
Run credential tests only from an approved administrative system. Do not expose the token through shell history, screenshots, terminal recordings, or logs.
### Configure Material 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 "**Material Security**", select the **Connections** tab, and click **+ New Connection** button.
4. Use the following values in the AirMDR integration configuration screen:
| AirMDR field | Required | Description | Example |
| ---------------- | ------------: | ------------------------------------------------------- | ------------------------------------------ |
| **Instance** | Yes | Unique name used to identify the connection. | `Material-Security-Production` |
| **Organization** | As applicable | AirMDR organization that owns the connection. | `AirMDR Organization` |
| **Description** | Yes | Purpose and environment of the connection. | `Material Security production integration` |
| **API Token** | Yes | Token generated from Material Security. | Enter as a secret |
| **Base URL** | Yes | Material Security tenant origin without a UI page path. | `https://acme.on.material.security` |
1. In **Remote Agent**, select an AirMDR Remote Agent only when the Material Security tenant must be accessed through an approved private network route, proxy, or controlled network environment.
2. In **Expiry**, select the date on which AirMDR should treat the stored connection credentials as expired, according to your organisation’s credential-rotation policy.
The AirMDR **Expiry** setting is a connection-management control. It does not automatically expire, revoke, or rotate the API token in Material Security.
Manage the token separately from **Integrations → API → Tokens** in the Material Security UI.
5. Click **Save**.
### Skills provided by this Integration
These read-only skills retrieve Material Security issues and their associated messages.
| **Skill ID** | **Purpose** | **Minimum Material Security Role** | **Required Access** |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `get_material_security_issues` | Retrieves one or more Material Security issues. Issues can be filtered by status, severity, entity type, detection, or time range. | **Issue Responder** | View issues and evidence. An **Analyst** role may be required when using the beta time-filtered API path. |
| `list_material_security_issue_messages` | Lists the email messages associated with a specific Material Security issue. | **Issue Responder** | View issues and message information associated with an issue. |
| `get_material_security_case_details` | Retrieves phishing-case details and a subset of the messages associated with each case. | **Issue Responder** | View issue or case details and associated evidence. Beta API access must be validated for the service account. |
`get_material_security_issues` can use different API paths. Requests using an API v1 issue ID return encoded IDs such as `iss.1.`. Time-filtered requests may use the beta API and return UUID-based case IDs.
These skills search Material Security mail data or retrieve information about individual messages.
| **Skill ID** | **Purpose** | **Minimum Material Security Role** | **Required Access** |
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `search_material_security_messages` | Starts an asynchronous MQL search across messages in the Material Security tenant and returns a search-job ID. | **Analyst** for metadata-only searches; **Email Content Admin** for full content searches | Search messages. Full message-body access requires message-content permission. |
| `get_material_security_message_search_results` | Retrieves the status and results of a message-search job until the status reaches `DONE`. | **Analyst** for metadata-only results; **Email Content Admin** for message content | Search and view message metadata. Use the job ID returned by `search_material_security_messages`. |
| `get_material_security_message` | Retrieves message headers and, when requested, content, attachments, links, mailbox details, and the associated issue. | **Issue Responder** for issue-associated messages; **Email Content Admin** for arbitrary or full-content messages | View message metadata. Additional permission is required for message content, attachments, links, or mailboxes. |
Use `search_material_security_messages` first and then pass the returned job ID to `get_material_security_message_search_results`. Use a message ID from the completed results to call `get_material_security_message`.
These read-only skills retrieve Material Security account and detection information.
| **Skill ID** | **Purpose** | **Minimum Material Security Role** | **Required Access** |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- | ---------------------------------------------------------------------------------- |
| `list_material_security_accounts` | Searches Material Security accounts and returns account posture, status, role, licence, mailbox settings, delegates, forwarding configuration, and other security information. | **Any assigned Material Security admin role** | View account, group, and tenant details. |
| `get_material_security_detections` | Retrieves Material Security detection rules, configuration, severity, rollout state, domain overrides, and issue counts. | **Any assigned Material Security admin role** | View detections. Material Security allows all roles to view detection information. |
These state-changing skills update issues or cases and may apply remediation actions.
| **Skill ID** | **Purpose** | **Minimum Material Security Role** | **Required Access** |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `update_material_security_issue` | Updates an issue’s status, classification, assignee, snooze settings, or remediation actions. | **Issue Responder** | Update issues and apply issue-level remediation. Specific actions may require permission to delete or modify issue-associated messages. |
| `update_material_security_case_status` | Updates the status and remediation settings of one Material Security phishing case. | **Issue Responder** | Update issue or case status and apply remediation. Beta API access must be validated. |
| `update_material_security_case_statuses` | Updates multiple Material Security cases in one request using either shared or case-specific decisions. | **Issue Responder** | Update and remediate multiple issues or cases. Beta API access must be validated. |
These skills change investigation state and can affect what users can access. Confirm the analyst verdict and target case IDs before execution.
Updating remediation on an issue can replace the existing remediation-action list rather than merge new actions into it. Include all actions that must remain active.
These skills classify messages or change how users can access them.
| **Skill ID** | **Purpose** | **Minimum Material Security Role** | **Required Access** |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------- |
| `mark_material_security_messages_suspicious` | Reports one or more messages as suspicious and starts Material Security triage or case-creation processing. | **Analyst** | Create an Email Threat issue from a message and submit suspicious-message jobs. |
| `mark_material_security_messages_sensitive` | Marks messages as sensitive or insensitive and can trigger Material Security email-redaction controls. | **Analyst** | Mark messages as sensitive. Message-search access may also be required to identify target messages. |
Marking a message as sensitive can place it behind an end-user reauthentication challenge. Validate the target messages, accounts, and tenant scope before execution.
Trusted entities are domains, email addresses, IP addresses, or CIDR ranges that Material Security treats as known and trusted.
| **Skill ID** | **Purpose** | **Minimum Material Security Role** | **Required Access** |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------ |
| `get_material_security_trusted_entities` | Lists trusted entities or retrieves the configuration and history of a specific trusted entity. | **Analyst** or **Settings Admin** | View trusted entities. Timeline access is required when change history is requested. |
These skills change what Material Security treats as trusted and must be tightly controlled.
| **Skill ID** | **Purpose** | **Minimum Material Security Role** | **Required Access** |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------- |
| `create_material_security_trusted_entity` | Creates a trusted domain, email address, IP address, or CIDR range. | **Analyst** or **Settings Admin** | Trusted Entities write permission. |
| `update_material_security_trusted_entity` | Updates an existing trusted entity’s enabled state and detection or authentication settings. | **Analyst** or **Settings Admin** | Trusted Entities write permission. |
| `bulk_update_material_security_trusted_entities` | Performs up to 200 trusted-entity create, update, or delete operations in one request. | **Analyst** or **Settings Admin** | Trusted Entities write permission, including permission for every requested operation. |
| `delete_material_security_trusted_entity` | Permanently removes a tenant-created trusted entity. | **Analyst** or **Settings Admin** | Trusted Entities delete/write permission. System-managed entities cannot be deleted. |
Trusted-entity changes are security-sensitive and audited. They directly affect what Material Security treats as safe.
To temporarily stop a trusted entity from applying, use `update_material_security_trusted_entity` with `enabled=false` instead of deleting it. Disabling the entity is reversible and preserves its settings and history.
Bulk operations are processed independently and are not transactional. Review every operation result because some operations may succeed while others fail.
These administrative skills modify account or detection settings.
| **Skill ID** | **Purpose** | **Minimum Material Security Role** | **Required Access** |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `update_material_security_account_settings` | Updates settings for a Material Security account, including challenge delegates, feature overrides, and VIP designation. | **Settings Admin** | Update account settings and, when used, update Material delegates or organisational-profile settings. |
| `update_material_security_detections` | Enables or disables Material Security detections and applies global or tenant-domain overrides. | **Analyst** | Update detections, including enablement, severity, and response configuration. |
Disabling a detection can stop Material Security from generating issues for that threat class. Prefer a tenant-domain override instead of changing the global default when only one tenant is affected.
Adding a challenge delegate can allow another user to complete identity challenges for the target account. Confirm the request and target account before executing the skill.
To view the details of Input Parameters and Output for the respective skills
* Go to [AirMDR → Material Security](https://app.airmdr.com/integrationsv2/f78b91fd-c535-48ab-ad8b-ef4756400a33/skills?search=material) Integration page.
* Select the **Skills** tab and click on the required listed skills.
## Additional Information
| Symptom | Possible cause | Resolution |
| ------------------------------------------ | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized` | Missing, invalid, revoked, or incorrectly copied token. | Copy or generate a valid token, update the connection, and retry. |
| Authentication header error | The `x-material-client-secret` header was not sent. | Verify the AirMDR connector is using the configured API Token field. |
| Permission or access error | The service account lacks the required permission. | Review the account’s current Material Security role and assign only the required permission. |
| Endpoint not found | The Base URL contains a UI path or an incorrect API path. | Enter only the tenant origin in the Base URL field. |
| DNS error | The tenant hostname cannot be resolved. | Verify the hostname and DNS configuration on AirMDR or the Remote Agent. |
| TLS error | Certificate validation, proxy, or TLS-inspection problem. | Verify the certificate chain and network security configuration. Do not disable certificate validation. |
| Connection timeout | Firewall, proxy, routing, or Remote Agent issue. | Verify outbound TCP `443` connectivity and the selected Remote Agent. |
| Empty API response | No matching records or insufficient visibility. | Test with a known record and verify the service-account permissions. |
| Test works with `curl` but fails in AirMDR | Incorrect saved value, stale token, or Remote Agent routing issue. | Re-enter the token, verify the Base URL, and review the AirMDR execution details. |
### Material Security Audit Log
Material Security records API-related events in the **Audit Log**.
API events display an API icon beside the actor.
To view events associated with a particular token:
1. Go to Integrations → API → Tokens
2. Select one token row.
3. Select **View Audit Events**.
4. The Material Security Audit Log opens with filters applied for:
* The selected token
* Events from the previous week
5. Update the time filter when investigating older activity.
The filtered Audit Log displays events for one token only. An account can have multiple tokens, so the results might not include every API action performed by that account.
### AirMDR monitoring
For each integration execution:
* Review the AirMDR skill or playbook execution result.
* Record the connection instance used.
* Confirm the execution date, time, and action.
* Correlate the AirMDR execution with the Material Security Audit Log.
* Capture sanitized HTTP status and error information.
* Never record the API token or complete authentication header.
### Illustrative log entries
```text theme={null}
INFO integration=material_security instance=Material-Security-Production action=list_issues result=success
```
```text theme={null}
WARN integration=material_security status=401 message="Authentication failed; verify the configured API token"
```
```text theme={null}
ERROR integration=material_security action=list_issues message="Connection to tenant endpoint failed"
```
### Recommended log levels
| Level | Recommended use |
| :------------------------------------------ | :------------------------------------------------------------------------------ |
| `INFO` | Successful connection tests and normal skill execution. |
| `WARN` | Authentication failures, permission failures, retries, or rate-limit responses. |
| `ERROR` | Unrecoverable API, network, or connector failures. |
| `DEBUG` | Temporary troubleshooting with sensitive fields redacted. |
| Do not record the following values in logs: | |
* API tokens
* Authentication headers
* Sensitive email content
* Message bodies
* Personal information
* Unnecessary attachment metadata
### ✅ Do
* Use a dedicated, least-privileged service account.
* Store the API token only in approved secret storage and the AirMDR secret field.
* Use separate tokens for production and non-production environments.
* Use separate AirMDR connection instances for each environment.
* Keep TLS certificate verification enabled.
* Rotate tokens periodically and after suspected exposure.
* Mask tokens and tenant-sensitive information in screenshots.
* Validate connection changes using a read-only operation.
* Monitor API activity through the Material Security Audit Log.
* Remove unused or outdated tokens.
### ❌ Don’t
* Using a personal account for production automation.
* Using a Super Admin or Tenant Admin token for routine operations.
* Reusing the same token across unrelated applications.
* Reusing production tokens in test environments.
* Adding Material Security UI page paths to the Base URL.
* Adding `/api/v1` to the Base URL without connector-specific confirmation.
* Hardcoding tokens in scripts or source control.
* Adding tokens to documentation, Jira tickets, emails, or Slack messages.
* Disabling TLS certificate verification.
* Enabling verbose production logging that could expose headers or sensitive data.
* 📧 Contact [**AirMDR Support**](mailto:support@airmdr.com) through your designated support channel.
* 🔁 Rotate credentials regularly. Recommended cadence: Every 90 days or as per internal security policy
* 🔄 **Reconnect in AirMDR immediately when API Keys are changed.**
### Data exchanged
During integration execution:
* AirMDR sends the API token in the `x-material-client-secret` request header.
* AirMDR sends the parameters required by the selected skill.
* Material Security validates the token and the associated account permissions.
* Material Security returns the data allowed by the requested endpoint and account permissions.
* AirMDR processes the returned information within the relevant skill, playbook, workflow, or case.
Material API v1 documents resources such as:
* Security issues
* Email messages
* Trusted entities
The exact data accessed depends on the AirMDR skill being executed.
> **Important:** Document the data retrieved or modified by each AirMDR skill after confirming its implementation with the Integration SME.
### Network requirements
| Requirement | Value |
| :-------------------- | :-------------------------------------- |
| Protocol | HTTPS |
| Destination port | TCP `443` |
| Tenant origin | `https://.on.material.security` |
| API path prefix | `/api/v1` |
| Authentication header | `x-material-client-secret` |
| Direction | Outbound from AirMDR or Remote Agent |
### Encryption
**In transit**
API connections use HTTPS. AirMDR or the selected Remote Agent must validate the Material Security server certificate.
Do not disable TLS certificate verification to bypass connection errors.
**At rest**
The referenced Material Security API authentication documentation does not specify at-rest encryption algorithms or controls.
Confirm current at-rest encryption and compliance controls through Material Security’s approved security documentation, trust centre, or support channel before making a compliance claim