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

Trusted Entities

Overview

The Trusted Entities API provides programmatic access to your organization's Trusted Entities: allowlisted domains, email addresses, and IPs/CIDRs that tune how Material treats email and files from those identities. List and filter entities, retrieve one by ID (including its change timeline), and create, update, or delete entries individually or in bulk. System-managed entities (auto-enrolled domains and Material defaults) can be customized but can't be deleted. Customizing one creates an override of its default settings.

Six endpoints make up the Trusted Entities API:

  • List Trusted Entities (GET /api/v1/trusted-entities): filter and retrieve a paginated list of Trusted Entities

  • Get Trusted Entity (GET /api/v1/trusted-entities/{id}): retrieve a single Trusted Entity by its encoded ID

  • Create Trusted Entity (POST /api/v1/trusted-entities): create a new Trusted Entity

  • Update Trusted Entity (PATCH /api/v1/trusted-entities/{id}): update the editable settings of an existing Trusted Entity

  • Delete Trusted Entity (DELETE /api/v1/trusted-entities/{id}): delete a Trusted Entity

  • Bulk Trusted Entities (POST /api/v1/trusted-entities/bulk): apply up to 200 create, update, or delete operations in one request

Response Structure

List responses follow the standard two-part structure:

  • meta: pagination metadata, including limit, hasMore, and nextCursor. Unlike other paginated endpoints, totalCount isn't provided, because the list merges system-managed entities with the ones you've created. Use hasMore and nextCursor to page.

  • items: an array of Trusted Entity objects.

Results return system-managed entities first (auto-enrolled domains and Material defaults), followed by the entities you've created; each block is ordered by entity, then ID.

The include Parameter

By default, responses return each entity's settings. Pass include=timeline on the list or get endpoints to also return the change timeline (creation, comments, and setting updates).

Want a walkthrough?

Review Hello World.

Pagination and Rate Limiting

  • Material APIs use cursor-based pagination: you pass the nextCursor value from one response as the cursor parameter in the next request.

  • The limit parameter controls page size and is locked into the cursor, so later pages keep the page size of the first request.

  • Every paginated response includes a meta object with limit, hasMore, and nextCursor (totalCount isn't available for Trusted Entities).

  • When hasMore is false and nextCursor is null, you've reached the last page.

List Trusted Entities

get

Retrieves a paginated list of Trusted Entities: allowlisted domains, email addresses, and IPs or CIDR ranges. Results return system-managed entities first (auto-enrolled domains and Material defaults), then the entities you've created, with each block ordered by entity and then ID. Filter by type, enabled state, and tenant. totalCount is not provided for this endpoint, so use meta.hasMore and meta.nextCursor to page.

Authorizations
x-material-client-secretstringRequired

Material Security API key

Query parameters
cursorstringOptional

The pagination cursor returned in a previous response. Pass this value to retrieve the next page of results.

Example: eyJ2IjoxLCJvIjoyNSwibCI6MjV9
limitintegerOptional

The maximum number of items to return per page.

Example: 25
typestringOptional

Filter by types (comma-separated).

Example: external_domain,internal_domain
enabledbooleanOptional

Filter to enabled (true) or disabled (false).

tenantstringOptional

Filter to a specific tenant, as an encoded tenant ID (format tnt.1.<base64>).

Example: tnt.1.ZXhhbXBsZV9pZF8xMjMPattern: ^[a-z]{1,6}\.[0-9]{1,2}\.[A-Za-z0-9_-]+$
includestringOptional

Comma-separated includes. Supported: timeline.

Example: timeline
Responses
200

Successful response

application/json
get/api/v1/trusted-entities
GET /api/v1/trusted-entities HTTP/1.1
Host: your-instance.on.material.security
x-material-client-secret: YOUR_API_KEY
Accept: */*

{
  "meta": {
    "totalCount": 1,
    "limit": 1,
    "hasMore": true,
    "nextCursor": "text"
  },
  "items": [
    {
      "id": "te.1.ZXhhbXBsZV9pZF8xMjM",
      "entity": "evil.com",
      "type": "external_domain",
      "tenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM",
      "enabled": true,
      "subdomains": "included",
      "emailThreatDetection": "detect",
      "emailAuthentication": "enforced",
      "fileDetection": "treat_as_internal",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "updatedBy": "acct.1.ZXhhbXBsZV9pZF8xMjM",
      "timeline": {
        "meta": {
          "totalCount": 1,
          "limit": 1,
          "hasMore": true,
          "nextCursor": "text"
        },
        "items": [
          {
            "type": "created",
            "at": "2026-01-01T00:00:00.000Z",
            "actor": "acct.1.ZXhhbXBsZV9pZF8xMjM",
            "detail": "text"
          }
        ]
      }
    }
  ]
}

Create Trusted Entity

post

Creates a Trusted Entity. entity and type are required; other settings default to the least-permissive values. Returns 200 with the created entity.

Authorizations
x-material-client-secretstringRequired

Material Security API key

Body
entitystringRequired

The domain, email address, or IP/CIDR to allowlist.

Example: evil.com
typestring · enumRequired

The kind of identity to allowlist: external_domain, internal_domain, email_address, or ip_address.

Possible values:
tenantstring · nullableOptional

The encoded ID of the tenant this entry applies to. Format: tnt.1.<base64>. Omit or set to null to apply globally across all tenants.

Example: tnt.1.ZXhhbXBsZV9pZF8xMjM
enabledbooleanOptional

Whether the entry is active. Defaults to true.

Default: true
subdomainsstring · enumOptional

Whether to also cover subdomains of the domain: included or not_included. Domain entities only; rejected for email address and IP entities.

Possible values:
emailThreatDetectionstring · enumOptional

The email threat handling for messages from this entity: detect (detect threats normally), ignore_mark_safe (create issues, but mark messages safe), or ignore_dont_create_issues (don't create phishing issues). Defaults to detect.

Default: detectPossible values:
emailAuthenticationstring · enumOptional

The email authentication handling for this entity: enforced (don't trust messages that fail authentication) or ignored (trust messages regardless of authentication). Defaults to enforced.

Default: enforcedPossible values:
fileDetectionstring · enumOptional

The file detection handling for this entity: treat_as_internal (treat entity as internal) or treat_as_external (treat entity as external). Domain and email address entities only; rejected for IP entities.

Possible values:
Responses
200

Successful response

application/json

An organization-level allowlist entry (a domain, email address, or IP/CIDR) that tunes how Material treats mail and files from that identity.

idstringRequired

The encoded trusted-entity ID. Format: te.1.<base64>.

Example: te.1.ZXhhbXBsZV9pZF8xMjM
entitystringRequired

The domain, email address, or IP/CIDR this entry allowlists.

Example: evil.com
typestring · enumRequired

The kind of identity this entry allowlists: external_domain, internal_domain, email_address, or ip_address.

Possible values:
tenantstring · nullableRequired

The encoded ID of the tenant this entry applies to. Format: tnt.1.<base64>. null means it applies globally across all tenants.

Example: tnt.1.ZXhhbXBsZV9pZF8xMjM
enabledbooleanRequired

Whether this Trusted Entity is active.

subdomainsstring · enum · nullableRequired

Whether the entry also covers subdomains of the domain: included or not_included. Applies to domain entities only; null for email address and IP entities.

Possible values:
emailThreatDetectionstring · enumRequired

The email threat handling for messages from this entity: detect (detect threats normally), ignore_mark_safe (create issues, but mark messages safe), or ignore_dont_create_issues (don't create phishing issues).

Possible values:
emailAuthenticationstring · enumRequired

The email authentication handling for this entity: enforced (don't trust messages that fail authentication) or ignored (trust messages regardless of authentication).

Possible values:
fileDetectionstring · enum · nullableRequired

The file detection handling for this entity: treat_as_internal (treat entity as internal) or treat_as_external (treat entity as external). Applies to domain and email address entities only; null for IP entities.

Possible values:
updatedAtstring · date-time · nullableRequired

When the entry was last modified, in ISO 8601 format. null for system-managed entities.

updatedBystring · nullableRequired

The encoded account ID of the last editor. Format: acct.1.<base64>. null for system-managed entities.

Example: acct.1.ZXhhbXBsZV9pZF8xMjM
post/api/v1/trusted-entities
POST /api/v1/trusted-entities HTTP/1.1
Host: your-instance.on.material.security
x-material-client-secret: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 223

{
  "entity": "evil.com",
  "type": "external_domain",
  "tenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM",
  "enabled": true,
  "subdomains": "included",
  "emailThreatDetection": "detect",
  "emailAuthentication": "enforced",
  "fileDetection": "treat_as_internal"
}
{
  "id": "te.1.ZXhhbXBsZV9pZF8xMjM",
  "entity": "evil.com",
  "type": "external_domain",
  "tenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM",
  "enabled": true,
  "subdomains": "included",
  "emailThreatDetection": "detect",
  "emailAuthentication": "enforced",
  "fileDetection": "treat_as_internal",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "updatedBy": "acct.1.ZXhhbXBsZV9pZF8xMjM",
  "timeline": {
    "meta": {
      "totalCount": 1,
      "limit": 1,
      "hasMore": true,
      "nextCursor": "text"
    },
    "items": [
      {
        "type": "created",
        "at": "2026-01-01T00:00:00.000Z",
        "actor": "acct.1.ZXhhbXBsZV9pZF8xMjM",
        "detail": "text"
      }
    ]
  }
}

Get Trusted Entity

get

Retrieves a single Trusted Entity by its encoded ID. Use include=timeline to pull the change timeline.

Authorizations
x-material-client-secretstringRequired

Material Security API key

Path parameters
idstringRequired

Encoded trusted-entity id. Format: te.1.<base64>.

Example: te.1.ZXhhbXBsZV9pZF8xMjMPattern: ^[a-z]{1,6}\.[0-9]{1,2}\.[A-Za-z0-9_-]+$
Query parameters
includestringOptional

Comma-separated includes. Supported: timeline.

Example: timeline
Responses
200

Successful response

application/json

An organization-level allowlist entry (a domain, email address, or IP/CIDR) that tunes how Material treats mail and files from that identity.

idstringRequired

The encoded trusted-entity ID. Format: te.1.<base64>.

Example: te.1.ZXhhbXBsZV9pZF8xMjM
entitystringRequired

The domain, email address, or IP/CIDR this entry allowlists.

Example: evil.com
typestring · enumRequired

The kind of identity this entry allowlists: external_domain, internal_domain, email_address, or ip_address.

Possible values:
tenantstring · nullableRequired

The encoded ID of the tenant this entry applies to. Format: tnt.1.<base64>. null means it applies globally across all tenants.

Example: tnt.1.ZXhhbXBsZV9pZF8xMjM
enabledbooleanRequired

Whether this Trusted Entity is active.

subdomainsstring · enum · nullableRequired

Whether the entry also covers subdomains of the domain: included or not_included. Applies to domain entities only; null for email address and IP entities.

Possible values:
emailThreatDetectionstring · enumRequired

The email threat handling for messages from this entity: detect (detect threats normally), ignore_mark_safe (create issues, but mark messages safe), or ignore_dont_create_issues (don't create phishing issues).

Possible values:
emailAuthenticationstring · enumRequired

The email authentication handling for this entity: enforced (don't trust messages that fail authentication) or ignored (trust messages regardless of authentication).

Possible values:
fileDetectionstring · enum · nullableRequired

The file detection handling for this entity: treat_as_internal (treat entity as internal) or treat_as_external (treat entity as external). Applies to domain and email address entities only; null for IP entities.

Possible values:
updatedAtstring · date-time · nullableRequired

When the entry was last modified, in ISO 8601 format. null for system-managed entities.

updatedBystring · nullableRequired

The encoded account ID of the last editor. Format: acct.1.<base64>. null for system-managed entities.

Example: acct.1.ZXhhbXBsZV9pZF8xMjM
get/api/v1/trusted-entities/{id}
GET /api/v1/trusted-entities/{id} HTTP/1.1
Host: your-instance.on.material.security
x-material-client-secret: YOUR_API_KEY
Accept: */*

{
  "id": "te.1.ZXhhbXBsZV9pZF8xMjM",
  "entity": "evil.com",
  "type": "external_domain",
  "tenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM",
  "enabled": true,
  "subdomains": "included",
  "emailThreatDetection": "detect",
  "emailAuthentication": "enforced",
  "fileDetection": "treat_as_internal",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "updatedBy": "acct.1.ZXhhbXBsZV9pZF8xMjM",
  "timeline": {
    "meta": {
      "totalCount": 1,
      "limit": 1,
      "hasMore": true,
      "nextCursor": "text"
    },
    "items": [
      {
        "type": "created",
        "at": "2026-01-01T00:00:00.000Z",
        "actor": "acct.1.ZXhhbXBsZV9pZF8xMjM",
        "detail": "text"
      }
    ]
  }
}

Delete Trusted Entity

delete

Deletes a Trusted Entity by its encoded ID. System-managed entities, whether auto-enrolled or Material defaults, can't be deleted. Returns 204 No Content.

Authorizations
x-material-client-secretstringRequired

Material Security API key

Path parameters
idstringRequired

Encoded trusted-entity id. Format: te.1.<base64>.

Example: te.1.ZXhhbXBsZV9pZF8xMjMPattern: ^[a-z]{1,6}\.[0-9]{1,2}\.[A-Za-z0-9_-]+$
Body
objectOptional
Responses
400

Bad request: invalid parameters or request body

application/json
errorstringRequired

A human-readable description of the error.

delete/api/v1/trusted-entities/{id}
DELETE /api/v1/trusted-entities/{id} HTTP/1.1
Host: your-instance.on.material.security
x-material-client-secret: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 2

{}
{
  "error": "text",
  "validationFailures": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ]
}

Update Trusted Entity

patch

Updates the editable settings of a Trusted Entity. entity, type, and tenant can't be changed after creation. Only provided fields change. Updating a system-managed entity (auto-enrolled or Material) creates a customization that overrides its default settings.

Authorizations
x-material-client-secretstringRequired

Material Security API key

Path parameters
idstringRequired

Encoded trusted-entity id. Format: te.1.<base64>.

Example: te.1.ZXhhbXBsZV9pZF8xMjMPattern: ^[a-z]{1,6}\.[0-9]{1,2}\.[A-Za-z0-9_-]+$
Body
enabledbooleanOptional

Whether the entry is active.

subdomainsstring · enumOptional

Whether to also cover subdomains of the domain: included or not_included. Domain entities only.

Possible values:
emailThreatDetectionstring · enumOptional

The email threat handling for messages from this entity: detect (detect threats normally), ignore_mark_safe (create issues, but mark messages safe), or ignore_dont_create_issues (don't create phishing issues).

Possible values:
emailAuthenticationstring · enumOptional

The email authentication handling for this entity: enforced (don't trust messages that fail authentication) or ignored (trust messages regardless of authentication).

Possible values:
fileDetectionstring · enumOptional

The file detection handling for this entity: treat_as_internal (treat entity as internal) or treat_as_external (treat entity as external). Domain and email address entities only.

Possible values:
Responses
200

Successful response

application/json

An organization-level allowlist entry (a domain, email address, or IP/CIDR) that tunes how Material treats mail and files from that identity.

idstringRequired

The encoded trusted-entity ID. Format: te.1.<base64>.

Example: te.1.ZXhhbXBsZV9pZF8xMjM
entitystringRequired

The domain, email address, or IP/CIDR this entry allowlists.

Example: evil.com
typestring · enumRequired

The kind of identity this entry allowlists: external_domain, internal_domain, email_address, or ip_address.

Possible values:
tenantstring · nullableRequired

The encoded ID of the tenant this entry applies to. Format: tnt.1.<base64>. null means it applies globally across all tenants.

Example: tnt.1.ZXhhbXBsZV9pZF8xMjM
enabledbooleanRequired

Whether this Trusted Entity is active.

subdomainsstring · enum · nullableRequired

Whether the entry also covers subdomains of the domain: included or not_included. Applies to domain entities only; null for email address and IP entities.

Possible values:
emailThreatDetectionstring · enumRequired

The email threat handling for messages from this entity: detect (detect threats normally), ignore_mark_safe (create issues, but mark messages safe), or ignore_dont_create_issues (don't create phishing issues).

Possible values:
emailAuthenticationstring · enumRequired

The email authentication handling for this entity: enforced (don't trust messages that fail authentication) or ignored (trust messages regardless of authentication).

Possible values:
fileDetectionstring · enum · nullableRequired

The file detection handling for this entity: treat_as_internal (treat entity as internal) or treat_as_external (treat entity as external). Applies to domain and email address entities only; null for IP entities.

Possible values:
updatedAtstring · date-time · nullableRequired

When the entry was last modified, in ISO 8601 format. null for system-managed entities.

updatedBystring · nullableRequired

The encoded account ID of the last editor. Format: acct.1.<base64>. null for system-managed entities.

Example: acct.1.ZXhhbXBsZV9pZF8xMjM
patch/api/v1/trusted-entities/{id}
PATCH /api/v1/trusted-entities/{id} HTTP/1.1
Host: your-instance.on.material.security
x-material-client-secret: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 141

{
  "enabled": true,
  "subdomains": "included",
  "emailThreatDetection": "detect",
  "emailAuthentication": "enforced",
  "fileDetection": "treat_as_internal"
}
{
  "id": "te.1.ZXhhbXBsZV9pZF8xMjM",
  "entity": "evil.com",
  "type": "external_domain",
  "tenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM",
  "enabled": true,
  "subdomains": "included",
  "emailThreatDetection": "detect",
  "emailAuthentication": "enforced",
  "fileDetection": "treat_as_internal",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "updatedBy": "acct.1.ZXhhbXBsZV9pZF8xMjM",
  "timeline": {
    "meta": {
      "totalCount": 1,
      "limit": 1,
      "hasMore": true,
      "nextCursor": "text"
    },
    "items": [
      {
        "type": "created",
        "at": "2026-01-01T00:00:00.000Z",
        "actor": "acct.1.ZXhhbXBsZV9pZF8xMjM",
        "detail": "text"
      }
    ]
  }
}

Bulk Trusted Entities

post

Applies up to 200 create/update/delete operations in one request, best-effort with per-item results in request order (results[i] corresponds to operations[i]). A well-formed envelope always returns 200; individual failures are reported in results[].

Authorizations
x-material-client-secretstringRequired

Material Security API key

Body
operationsone of[] · min: 1 · max: 200Required

Up to 200 operations, applied best-effort with per-item results.

or
or
Responses
200

Successful response

application/json
resultsone of[]Required

Per-operation result, in the same order as the request.

or
post/api/v1/trusted-entities/bulk
POST /api/v1/trusted-entities/bulk HTTP/1.1
Host: your-instance.on.material.security
x-material-client-secret: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 265

{
  "operations": [
    {
      "method": "text",
      "body": {
        "entity": "evil.com",
        "type": "external_domain",
        "tenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM",
        "enabled": true,
        "subdomains": "included",
        "emailThreatDetection": "detect",
        "emailAuthentication": "enforced",
        "fileDetection": "treat_as_internal"
      }
    }
  ]
}
{
  "results": [
    {
      "method": "create",
      "status": "text",
      "index": 1,
      "id": "text",
      "entity": {
        "id": "te.1.ZXhhbXBsZV9pZF8xMjM",
        "entity": "evil.com",
        "type": "external_domain",
        "tenant": "tnt.1.ZXhhbXBsZV9pZF8xMjM",
        "enabled": true,
        "subdomains": "included",
        "emailThreatDetection": "detect",
        "emailAuthentication": "enforced",
        "fileDetection": "treat_as_internal",
        "updatedAt": "2026-01-01T00:00:00.000Z",
        "updatedBy": "acct.1.ZXhhbXBsZV9pZF8xMjM",
        "timeline": {
          "meta": {
            "totalCount": 1,
            "limit": 1,
            "hasMore": true,
            "nextCursor": "text"
          },
          "items": [
            {
              "type": "created",
              "at": "2026-01-01T00:00:00.000Z",
              "actor": "acct.1.ZXhhbXBsZV9pZF8xMjM",
              "detail": "text"
            }
          ]
        }
      }
    }
  ],
  "meta": {
    "succeeded": 1,
    "failed": 1
  }
}
PreviousRoles
NextMaterial MCP Server

Last updated

Was this helpful?