API v1

Why use Material APIs?

The Material Security APIs give you programmatic access to the threat detection and email analysis data inside Material, so you can act on it outside the product.

One common use for the APIs is to integrate Material with a SOAR platform or other security tooling. For example, you can use the Issues API to list open issues, match them against signals in your existing workflows, and fetch full issue details, including related messages, accounts, and files, to enrich an incident or trigger a response action.

More broadly, the APIs are useful any time your team needs to analyze, export, or operationalize Material data in an external system.

What is Material API v1?

This API isn't just a new version of our beta API. We built API v1 from scratch around how developers actually use an API.

It covers Email Threat investigation and response end to end, along with the accounts, groups, roles, OAuth apps, and trusted entities behind them.

Note: The beta API remains available as-is for the foreseeable future. We won't break what you've already built. New release improvements will focus on API v1.

Beta API documentation is still available in the app.

---

Resources Overview

The Material Security API v1 includes these resources: Issues, Messages, Accounts, Groups, Roles, OAuth Apps, and Trusted Entities.

The Material Security API is growing fast. We're actively adding new resources. We'll let you know as they're released in What's New.

What do you want to see added next? Contact support to let us know.

Issues

An issue represents a detected threat or anomaly in your environment. Issues are created automatically when Material's detections fire, and track the full lifecycle of a threat, from initial detection through investigation and resolution. Each issue includes a severity level, classification, and a reference to the primary entity involved, such as an account, message, or file.

Use the Issues API to query and filter issues by status, retrieve full issue details, and fetch the email messages at the center of each threat.

Messages

A message represents an email ingested and analyzed by Material. Messages are the primary evidence attached to most issues, and can be retrieved individually or searched across in bulk using MQL (Material Query Language).

Use the Messages API to retrieve a specific message by ID, or run an asynchronous search to find messages matching criteria such as sender, subject, or date range.

Accounts

An account represents a directory account synced from Google Workspace or Microsoft 365. Each one carries its VIP designation, licenses, effective settings and the level each value comes from, mailbox state, provider status, and role assignments.

Use the Accounts API to list and filter accounts, retrieve a single account along with its group memberships, and update VIP designation, licenses, per-account setting overrides, and role assignments, either one account at a time or in bulk.

Groups

A group represents a directory group synced from your provider, including Google groups and org units, Microsoft groups, and Okta groups. Each one carries licenses, per-group setting overrides, and the roles it grants its members.

Use the Groups API to list and filter groups, retrieve a single group, list the accounts that belong to it, and update groups either one at a time or in bulk.

Roles

A role determines what an admin can do in Material. Role definitions are built in, so you manage assignments rather than the roles themselves.

Use the Roles API to list the roles you can assign on your instance, then assign them by updating an account or a group.

OAuth Apps

An OAuth app represents a third-party app holding token grants in your Google Workspace tenant, along with the scopes it was granted, its classification, and its standing remediation policy.

Use the OAuth Apps API to list and filter apps, retrieve a single app with its investigation results, list the accounts that granted it, update its classification and remediation, and revoke an individual account's grant.

Trusted Entities

A trusted entity is a domain, email address, or IP address or CIDR range that your instance treats as trusted.

Use the Trusted Entities API to review what your instance already trusts, then add, retrieve, update, and delete the entities you manage.

---

Material API v1 Guides

🔐 Authentication

How to get an API token

🌎 Hello World

Walkthroughs for your first calls to every API v1 resource

⁉️ Errors and Troubleshooting

Logging, tokens, and FAQs

API Reference

The complete technical specification for Material API V1, covering every endpoint, request parameter, response object, and field, including valid values, data types, and formats.

• Accounts

• Groups

• Issues

• Messages

• OAuth Apps

• Roles

• Trusted Entities