Material Security

Purpose

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

Supported Versions

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://<tenant>.on.material.security/api/v1/<resource>

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.

Authentication

Material Security uses token-based authentication.AirMDR sends the API token in the following request header: x-material-client-secret: <API_TOKEN>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.

Role-based access considerations

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

Identify the Material Security Base URL

Sign in to the Material Security UI.
In the browser address bar, identify your tenant URL. The URL follows this format: https://<your-tenant>.on.material.security
Copy only the protocol and hostname.
Remove any:
- Page path
- Query parameters
- URL fragment
- Trailing slash
  Example: Material Security browser URL: https://acme.on.material.security/integrations/api/tokens
  Enter the following value in the AirMDR Base URL field:
  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.

Generate the API Token

Sign in to Material Security using the dedicated service account.
From the top toolbar, select Integrations.
Navigate to API → Tokens.
On the API Tokens page, select Create Token.
Enter a descriptive name that identifies the integration, environment, and purpose for the token.
For example: AirMDR-Production-Integration.
Select the generated token box to copy the token to the clipboard.
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.	`<API_TOKEN>`
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:

Sample Request

curl --request GET \
  --url "${MATERIAL_BASE_URL}/api/v1/issues?status=open&limit=1" \
  --header "x-material-client-secret: ${MATERIAL_API_TOKEN}"

Sample Response

<AccordionGroup>
  <Accordion title='{  "meta": {    "totalCount": 1,    "limit": 1,    "hasMore": false,    "nextCursor": null  },  "items": [    {      "id": "example-issue-id",      "name": "Example security issue",      "status": "open"    }  ]}'>
    \{
      "meta": \{
        "totalCount": 1,
        "limit": 1,
        "hasMore": false,
        "nextCursor": null
      \},
      "items": [
        \{
          "id": "example-issue-id",
          "name": "Example security issue",
          "status": "open"
        \}
      ]
    \}
  </Accordion>
</AccordionGroup>

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

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 “Material Security”, select the Connections tab, and click + New Connection button.

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`

Expand Advanced Configuration if required. (Optional)

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.
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.

Click Save.

Skills provided by this Integration

Issue Investigation Skills

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.<base64>. Time-filtered requests may use the beta API and return UUID-based case IDs.

Message Search and Retrieval Skills

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.

Account and Detection Investigation Skills

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.

Issue and Case Response Skills

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.

Message Classification and Protection Skills

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 Entity Read Skills

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.

Trusted Entity Management Skills

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.

Account and Detection Configuration Skills

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 Integration page.
Select the Skills tab and click on the required listed skills.

Additional Information

🧰 Error Handling

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.

🔄 Monitoring & Logs

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:

Go to Integrations → API → Tokens
Select one token row.
Select View Audit Events.
The Material Security Audit Log opens with filters applied for:
- The selected token
- Events from the previous week

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

INFO integration=material_security instance=Material-Security-Production action=list_issues result=success

WARN integration=material_security status=401 message="Authentication failed; verify the configured API token"

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

🛑 Security & Access Best Practices

✅ 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.

👉 Support & Maintenance

📧 Contact AirMDR Support 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 Flow & Security

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://<tenant>.on.material.security`
API path prefix	`/api/v1`
Authentication header	`x-material-client-secret`
Direction	Outbound from AirMDR or Remote Agent

Encryption

In transitAPI 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 restThe 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

Getting Started

AirMDR Detections

Integrations

API Reference

AirMDR Product Suite

Material Security

Pre-requisites

Setup Steps

Material Security Credential Reference Table

Validate Connectivity

Configure Material Security in AirMDR Integrations Dashboard

Skills provided by this Integration

Additional Information

Material Security Audit Log

AirMDR monitoring

Illustrative log entries

Recommended log levels

✅ Do

❌ Don’t

Data exchanged

Network requirements

Encryption

​Pre-requisites

​Setup Steps

​Material Security Credential Reference Table

​Validate Connectivity

​Configure Material Security in AirMDR Integrations Dashboard

​Skills provided by this Integration

​Additional Information

​Material Security Audit Log

​AirMDR monitoring

​Illustrative log entries

​Recommended log levels

​✅ Do

​❌ Don’t

​Data exchanged

​Network requirements

​Encryption

Pre-requisites

Setup Steps

Material Security Credential Reference Table

Validate Connectivity

Configure Material Security in AirMDR Integrations Dashboard

Skills provided by this Integration

Additional Information

Material Security Audit Log

AirMDR monitoring

Illustrative log entries

Recommended log levels

✅ Do

❌ Don’t

Data exchanged

Network requirements

Encryption