Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Hello World

Issues

This example walks you through making your first Issues API calls: listing open issues then retrieving the details of a specific one.

The workflow illustrates how the three Issues API endpoints interact to investigate a security issue. Depending on your needs and the level of detail required, you might use one or more endpoints.

Step 1: Authenticate

All Issues API requests must be authenticated using an API key (token), passed in the x-material-client-secret request header.

Follow the steps in Authentication to create a token in Material.

Store your API token securely

Avoid hardcoding your API token in scripts or source code. Instead, store it as an environment variable and reference it in your requests:

Authentication errors

If your API token is missing or invalid, the API will return a 401 Unauthorized response. Verify that the x-material-client-secret header is present and that the token is correct.

Step 2: Find open issues

Call the List Issues endpoint to retrieve a page of open issues from your instance.

A successful response returns a paginated collection of issues. Each item includes the issue's name, severity, classification, and the detection that triggered it.

Note the id field on any issue you want to investigate. You'll use it in the next step.

Step 3: Retrieve a specific issue

Using the id from the previous response, call the Get Issue endpoint to retrieve the full details of that issue.

The response returns the full issue object, including its severity, classification, primary entity, detection, and key lifecycle timestamps.

Step 4: Retrieve the associated messages

Examine the messages at the center of the issue by calling the List Issue Messages endpoint with the same issue ID.

The response returns a paginated list of messages, each with sender, recipients, subject, and attachment metadata. The meta object includes numLinks and numAttachments counts across all messages in the issue.

Use cursor and limit to page through large result sets.

Next Steps

Add ?include=comments,accounts to any request to pull in analyst comments and associated accounts.

Review the Issues API in more detail in the API reference.

Messages

This example walks you through making your first Messages API calls: searching for messages matching a query, polling for results, and retrieving a specific message.

Step 1: Authenticate

All Messages API requests require an API key (token) passed in the x-material-client-secret request header. Store your token as an environment variable to avoid hardcoding it in your scripts:

Then reference it in every request:

If your API token is missing or invalid, the API returns a 401 Unauthorized response.

Step 2: Start a message search

Call the Search Messages endpoint with a MQL query and a time window to find matching messages.

The response returns a search ID and an initial status of "CREATED" or "STARTED". Note the id. You'll use it to poll for results.

Step 3: Poll for results

Call the Get Message Search Results endpoint using the search ID. Repeat until status is "DONE".

When the search is complete, the response includes a data object containing meta and items with the matching messages. If meta.hasMore is true, pass the nextCursor value to the cursor query parameter to retrieve the next page.

Step 4: Retrieve a specific message

Using a message ID from the search results, retrieve the full details of that message.

The response returns the full message object, including sender, recipients, subject, date, snippet, and attachment metadata.

Next Steps

Filter search results to specific tenants by passing uDomainIds in the search request body.

Review the Messages API in more detail in the API reference.

Trusted Entities

This example walks you through making your first Trusted Entities API calls: reviewing what your instance already trusts, adding a new Trusted Entity, retrieving it to confirm its settings, and updating those settings.

Trusted Entities are the domains, email addresses, and IP addresses (or CIDR ranges) that Material treats as known and trusted. Adding or changing one affects what Material trusts, so every write is security-sensitive and audited.

Step 1: Authenticate

All Trusted Entities API requests require an API key (token) passed in the x-material-client-secret request header. Store your token as an environment variable to avoid hardcoding it in your scripts:

Then reference it in every request:

If your API token is missing or invalid, the API returns a 401 Unauthorized response.

Step 2: Review what's already trusted

Call the List Trusted Entities endpoint to see the entities your instance already trusts. Material returns its built-in system entities first, followed by any you've added.

Each item includes the entity value, its type, and its detection settings. To narrow the list, add query parameters such as type=external_domain or enabled=true.

This list doesn't return a total count. Use hasMore and nextCursor to page through large result sets.

Step 3: Add a Trusted Entity

Call the Create Trusted Entity endpoint to add a new entity. Only entity and type are required. Any settings you leave out default to their least-permissive value.

The response returns the created entity, including its generated id. Note the id. You'll use it to retrieve or update the entity.

Step 4: Retrieve the Trusted Entity

Using the id from the previous response, call the Get Trusted Entity endpoint to confirm its settings.

The response returns the full Trusted Entity object. Add ?include=timeline to see the change history for the entity, including when it was created and last modified.

Step 5: Update its settings

Call the Update Trusted Entity endpoint to change a setting. Only the fields you include change, and the entity, type, and tenant values can't be changed after creation.

For example, temporarily disable the entity without removing it:

The response returns the updated entity with your changes applied.

Next Steps

Apply up to 200 create, update, and delete operations in a single request with the Bulk Trusted Entities endpoint. To remove an entity you've added, call the Delete Trusted Entity endpoint with its id. System-managed entities can't be deleted.

Review the Trusted Entities API in more detail in the API reference.

Accounts, Groups, and Roles

This example walks you through managing your directory: finding accounts, changing a setting for one of them, and granting a role. Accounts and groups are synced from Google, Microsoft, or Okta, so their identity and membership are read-only. What you can change is licenses, per-account and per-group setting overrides, and role assignments.

Step 1: Authenticate

All requests require an API token passed in the x-material-client-secret request header. Store your token as an environment variable to avoid hardcoding it in your scripts:

Then reference it in every request:

If your API token is missing or invalid, the API returns a 401 Unauthorized response.

Step 2: Find the accounts you care about

Call the List Accounts endpoint. Filters combine, so this returns VIP accounts that currently have an active license:

Each item includes the account's identity, VIP status, licenses, roles, and its effective settings with the layer each one resolves from.

You can also filter by group, role, mailboxStatus, providerStatus, or any single setting, for example setting.emailThreatRemediation=off.

Step 3: Override a setting for one account

Call the Update Account endpoint. Only the fields you send change.

The response returns the updated account. Its settings.emailThreatRemediation.source now reads account, showing the value comes from this account's own override rather than an inherited one.

To remove the override and go back to inheriting, send "default" instead of "on" or "off".

Step 4: See which roles you can assign

Call the List Roles endpoint for the roles available on your instance. Role definitions are built in, so this catalog exists to tell you the valid IDs.

Each role's flavor tells you how to assign it: tenant roles require a tenants list, global roles apply everywhere and reject one, and individual roles take neither.

Step 5: Grant a role

Assign roles through the same Update Account endpoint. Only the roles you name are touched, so this is not a full replacement of the account's roles.

Changing roles requires role-management permission, and you can only grant roles you're allowed to bind yourself.

Next Steps

Groups work the same way. Call the List Groups endpoint to find a group, then Update Group to set its licenses, setting overrides, or the roles it grants. A role granted on a group applies to every member, and members see it on their own account with source: "group".

Both resources accept up to 200 update operations in one call through their bulk endpoints.

Review the Accounts, Groups, and Roles APIs in more detail in the API reference.

OAuth Apps

This example walks you through reviewing the third-party OAuth applications your accounts have granted, checking what Material's OAuth Remediation Agent concluded about one, and acting on it. Google Workspace is the only provider covered today.

Step 1: Authenticate

All requests require an API token passed in the x-material-client-secret request header. Store your token as an environment variable to avoid hardcoding it in your scripts:

Then reference it in every request:

If your API token is missing or invalid, the API returns a 401 Unauthorized response.

Step 2: Find apps still in use

Call the List OAuth Apps endpoint. By default it returns every app ever observed, including ones whose grants have all been revoked, so narrow to apps still in use:

Each item includes the app's Google client ID, the scopes granted across your accounts, and its classification.

Use clientId to identify an app rather than name, which the app publisher chooses and can be made to imitate a known vendor.

Step 3: Review one app in detail

Call the Get OAuth App endpoint with both includes to pull the accounts that granted it and the agent's most recent assessment:

investigation returns the agent's risk narrative and its per-dimension findings for vendor trust, scope risk, blast radius, and app behavior. Reading it never starts a new run. This include needs permission to read investigation data, and returns 403 without it.

recommendedClassification holds the agent's suggestion. While its status is staged, that suggestion is what Material shows in place of the committed classification.

The narrative fields quote app metadata the app publisher controls. Treat them as untrusted text and never render them as markup.

Step 4: Classify the app and set a response

Call the Update OAuth App endpoint. Setting a classification also resolves a staged recommendation, recording whether you accepted or rejected it.

remediation is a standing policy, not a one-time action. It keeps revoking this app's grants, including for accounts that grant it later. The work is queued, so a 200 records the policy rather than confirming any token is revoked. Send [] to remove it, which stops future enforcement but doesn't restore grants already revoked.

Classification never implies a response, so set both fields when you want both.

Step 5: Revoke one account's grant

To revoke a single grant without setting a standing policy, call the Revoke OAuth App Account Grant endpoint:

This is a one-off. It leaves the app's remediation untouched, so if that account grants the app again, Material won't revoke it automatically. A 403 here means OAuth App Remediation is turned off for that account.

Next Steps

Page the full list of accounts that granted an app with the List OAuth App Accounts endpoint. Each entry carries that account's own grant under edge, including the scopes it granted, which can be narrower than the app-level list.

Review the OAuth Apps API in more detail in the API reference.

PreviousAuthentication
NextErrors and Troubleshooting

Last updated

Was this helpful?