> For the complete documentation index, see [llms.txt](https://docs.material.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.material.security/reference/api-v1/trusted-entities.md).

# Trusted Entities

**Overview**

The Trusted Entities API provides programmatic access to your organization's [trusted entities](https://docs.material.security/getting-started/fundamentals/detect/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**](https://docs.material.security/reference/api-v1/trusted-entities#get-api-v1-trusted-entities) (`GET /api/v1/trusted-entities`): filter and retrieve a paginated list of trusted entities
* [**Get Trusted Entity**](https://docs.material.security/reference/api-v1/trusted-entities#get-api-v1-trusted-entities-id) (`GET /api/v1/trusted-entities/{id}`): retrieve a single trusted entity by its encoded ID
* [**Create Trusted Entity**](https://docs.material.security/reference/api-v1/trusted-entities#post-api-v1-trusted-entities) (`POST /api/v1/trusted-entities`): create a new trusted entity
* [**Update Trusted Entity**](https://docs.material.security/reference/api-v1/trusted-entities#patch-api-v1-trusted-entities-id) (`PATCH /api/v1/trusted-entities/{id}`): update the editable settings of an existing trusted entity
* [**Delete Trusted Entity**](https://docs.material.security/reference/api-v1/trusted-entities#delete-api-v1-trusted-entities-id) (`DELETE /api/v1/trusted-entities/{id}`): delete a trusted entity
* [**Bulk Trusted Entities**](https://docs.material.security/reference/api-v1/trusted-entities#post-api-v1-trusted-entities-bulk) (`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](https://docs.material.security/reference/api-v1/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

> Retrieves a paginated list of trusted entities (allowlisted domains, email addresses, and IPs/CIDRs). Results are returned system entities first (auto-enrolled + Material), then stored entities, each block ordered by entity then id. Filter by type, enabled state, and tenant. \`totalCount\` is not provided for this endpoint; use \`meta.hasMore\`/\`meta.nextCursor\` to page.

```json
{"openapi":"3.1.0","info":{"title":"Material Security API","version":"v1"},"tags":[{"name":"Trusted Entities","description":"**Overview**\n\nThe Trusted Entities API provides programmatic access to your organization's [trusted entities](https://docs.material.security/getting-started/fundamentals/detect/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.\n\nSix endpoints make up the Trusted Entities API:\n\n* **[List Trusted Entities](https://docs.material.security/reference/api-v1/trusted-entities#get-api-v1-trusted-entities)** (`GET /api/v1/trusted-entities`): filter and retrieve a paginated list of trusted entities\n* **[Get Trusted Entity](https://docs.material.security/reference/api-v1/trusted-entities#get-api-v1-trusted-entities-id)** (`GET /api/v1/trusted-entities/{id}`): retrieve a single trusted entity by its encoded ID\n* **[Create Trusted Entity](https://docs.material.security/reference/api-v1/trusted-entities#post-api-v1-trusted-entities)** (`POST /api/v1/trusted-entities`): create a new trusted entity\n* **[Update Trusted Entity](https://docs.material.security/reference/api-v1/trusted-entities#patch-api-v1-trusted-entities-id)** (`PATCH /api/v1/trusted-entities/{id}`): update the editable settings of an existing trusted entity\n* **[Delete Trusted Entity](https://docs.material.security/reference/api-v1/trusted-entities#delete-api-v1-trusted-entities-id)** (`DELETE /api/v1/trusted-entities/{id}`): delete a trusted entity\n* **[Bulk Trusted Entities](https://docs.material.security/reference/api-v1/trusted-entities#post-api-v1-trusted-entities-bulk)** (`POST /api/v1/trusted-entities/bulk`): apply up to 200 create, update, or delete operations in one request\n\n**Response Structure**\n\nList responses follow the standard two-part structure:\n\n* **`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.\n* **`items`**: an array of trusted entity objects.\n\nResults 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.\n\n**The `include` Parameter**\n\nBy 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).\n\n**Want a walkthrough?**\n\nReview [Hello World](https://docs.material.security/reference/api-v1/hello-world).\n\n**Pagination and Rate Limiting**\n\n* Material APIs use **cursor-based pagination**: you pass the `nextCursor` value from one response as the `cursor` parameter in the next request.\n* The `limit` parameter controls page size and is locked into the cursor, so later pages keep the page size of the first request.\n* Every paginated response includes a `meta` object with `limit`, `hasMore`, and `nextCursor` (`totalCount` isn't available for trusted entities).\n* When `hasMore` is false and `nextCursor` is null, you've reached the last page.\n"}],"servers":[{"url":"https://{domain}","description":"Material Security instance","variables":{"domain":{"default":"your-instance.on.material.security","description":"Your Material Security instance domain"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-material-client-secret","description":"Material Security API key"}},"schemas":{"APITrustedEntityCollection":{"title":"APITrustedEntityCollection","type":"object","properties":{"meta":{"$ref":"#/components/schemas/CollectionMeta"},"items":{"type":"array","items":{"$ref":"#/components/schemas/APITrustedEntity"}}},"required":["meta","items"]},"CollectionMeta":{"title":"CollectionMeta","type":"object","properties":{"totalCount":{"description":"The total number of items matching the query.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"description":"The page size used for this response.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hasMore":{"description":"True if more items exist beyond the current page; false otherwise.","type":"boolean"},"nextCursor":{"description":"The cursor to fetch the next page of results. Pass this value to the `cursor` query parameter. Null if no more pages exist.","anyOf":[{"type":"string"},{"type":"null"}]}}},"APITrustedEntity":{"title":"APITrustedEntity","description":"An organization-level allowlist entry (a domain, email address, or IP/CIDR) that tunes how Material treats mail and files from that identity.","type":"object","properties":{"id":{"description":"The encoded trusted-entity ID. Format: `te.1.<base64>`.","type":"string"},"entity":{"description":"The domain, email address, or IP/CIDR this entry allowlists.","type":"string"},"type":{"description":"The kind of identity this entry allowlists: `external_domain`, `internal_domain`, `email_address`, or `ip_address`.","type":"string","enum":["external_domain","internal_domain","email_address","ip_address"]},"tenant":{"description":"The encoded ID of the tenant this entry applies to. Format: `tnt.1.<base64>`. `null` means it applies globally across all tenants.","anyOf":[{"type":"string"},{"type":"null"}]},"enabled":{"description":"Whether this trusted entity is active.","type":"boolean"},"subdomains":{"description":"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.","anyOf":[{"type":"string","enum":["included","not_included"]},{"type":"null"}]},"emailThreatDetection":{"description":"The [email threat handling](https://docs.material.security/getting-started/fundamentals/detect/trusted-entities#settings-definitions) 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).","type":"string","enum":["detect","ignore_mark_safe","ignore_dont_create_issues"]},"emailAuthentication":{"description":"The [email authentication handling](https://docs.material.security/getting-started/fundamentals/detect/trusted-entities#settings-definitions) for this entity: `enforced` (don't trust messages that fail authentication) or `ignored` (trust messages regardless of authentication).","type":"string","enum":["enforced","ignored"]},"fileDetection":{"description":"The [file detection handling](https://docs.material.security/getting-started/fundamentals/detect/trusted-entities#settings-definitions) 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.","anyOf":[{"type":"string","enum":["treat_as_internal","treat_as_external"]},{"type":"null"}]},"updatedAt":{"description":"When the entry was last modified, in ISO 8601 format. `null` for system-managed entities.","anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedBy":{"description":"The encoded account ID of the last editor. Format: `acct.1.<base64>`. `null` for system-managed entities.","anyOf":[{"type":"string"},{"type":"null"}]},"timeline":{"description":"The change timeline for this entry. Populated only when `include=timeline`.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/CollectionMeta"},"items":{"type":"array","items":{"$ref":"#/components/schemas/APITrustedEntityTimelineEvent"}}},"required":["meta","items"]}},"required":["id","entity","type","tenant","enabled","subdomains","emailThreatDetection","emailAuthentication","fileDetection","updatedAt","updatedBy"]},"APITrustedEntityTimelineEvent":{"title":"APITrustedEntityTimelineEvent","type":"object","properties":{"type":{"description":"The timeline type: `created`, `comment`, or `setting_updated`.","type":"string"},"at":{"description":"When the event occurred, in ISO 8601 format. `null` for system events.","anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"actor":{"description":"The encoded account ID of the account that triggered the event. Format: `acct.1.<base64>`. `null` for system events.","anyOf":[{"type":"string"},{"type":"null"}]},"detail":{"description":"The comment text or the setting name that changed. `null` when neither applies.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","at","actor","detail"]},"ValidationErrorResponse":{"title":"Validation Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"},"validationFailures":{"description":"List of individual validation failures when request parameters fail schema validation.","type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["error"]},"ErrorResponse":{"title":"Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"}},"required":["error"]}}},"paths":{"/api/v1/trusted-entities":{"get":{"operationId":"listTrustedEntities","summary":"List Trusted Entities","description":"Retrieves a paginated list of trusted entities (allowlisted domains, email addresses, and IPs/CIDRs). Results are returned system entities first (auto-enrolled + Material), then stored entities, each block ordered by entity then id. Filter by type, enabled state, and tenant. `totalCount` is not provided for this endpoint; use `meta.hasMore`/`meta.nextCursor` to page.","tags":["Trusted Entities"],"parameters":[{"in":"query","name":"cursor","schema":{"description":"The pagination cursor returned in a previous response. Pass this value to retrieve the next page of results.","type":"string"},"description":"The pagination cursor returned in a previous response. Pass this value to retrieve the next page of results."},{"in":"query","name":"limit","schema":{"description":"The maximum number of items to return per page.","type":"integer"},"description":"The maximum number of items to return per page."},{"in":"query","name":"type","schema":{"description":"Filter by types (comma-separated).","type":"string"},"description":"Filter by types (comma-separated)."},{"in":"query","name":"enabled","schema":{"description":"Filter to enabled (true) or disabled (false).","type":"boolean"},"description":"Filter to enabled (true) or disabled (false)."},{"in":"query","name":"tenant","schema":{"description":"Filter to a specific tenant (encoded `tnt`).","type":"string","pattern":"^[a-z]{1,6}\\.[0-9]{1,2}\\.[A-Za-z0-9_-]+$"},"description":"Filter to a specific tenant (encoded `tnt`)."},{"in":"query","name":"include","schema":{"description":"Comma-separated includes. Supported: `timeline`.","type":"string"},"description":"Comma-separated includes. Supported: `timeline`."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APITrustedEntityCollection"}}}},"400":{"description":"Bad request: invalid parameters or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Unauthorized: missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: the API key doesn't have permission to perform this action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found: the requested resource doesn't exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Create Trusted Entity

> Creates a trusted entity. \`entity\` and \`type\` are required; other settings default to the least-permissive values. Returns 200 with the created entity.

```json
{"openapi":"3.1.0","info":{"title":"Material Security API","version":"v1"},"tags":[{"name":"Trusted Entities","description":"**Overview**\n\nThe Trusted Entities API provides programmatic access to your organization's [trusted entities](https://docs.material.security/getting-started/fundamentals/detect/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.\n\nSix endpoints make up the Trusted Entities API:\n\n* **[List Trusted Entities](https://docs.material.security/reference/api-v1/trusted-entities#get-api-v1-trusted-entities)** (`GET /api/v1/trusted-entities`): filter and retrieve a paginated list of trusted entities\n* **[Get Trusted Entity](https://docs.material.security/reference/api-v1/trusted-entities#get-api-v1-trusted-entities-id)** (`GET /api/v1/trusted-entities/{id}`): retrieve a single trusted entity by its encoded ID\n* **[Create Trusted Entity](https://docs.material.security/reference/api-v1/trusted-entities#post-api-v1-trusted-entities)** (`POST /api/v1/trusted-entities`): create a new trusted entity\n* **[Update Trusted Entity](https://docs.material.security/reference/api-v1/trusted-entities#patch-api-v1-trusted-entities-id)** (`PATCH /api/v1/trusted-entities/{id}`): update the editable settings of an existing trusted entity\n* **[Delete Trusted Entity](https://docs.material.security/reference/api-v1/trusted-entities#delete-api-v1-trusted-entities-id)** (`DELETE /api/v1/trusted-entities/{id}`): delete a trusted entity\n* **[Bulk Trusted Entities](https://docs.material.security/reference/api-v1/trusted-entities#post-api-v1-trusted-entities-bulk)** (`POST /api/v1/trusted-entities/bulk`): apply up to 200 create, update, or delete operations in one request\n\n**Response Structure**\n\nList responses follow the standard two-part structure:\n\n* **`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.\n* **`items`**: an array of trusted entity objects.\n\nResults 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.\n\n**The `include` Parameter**\n\nBy 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).\n\n**Want a walkthrough?**\n\nReview [Hello World](https://docs.material.security/reference/api-v1/hello-world).\n\n**Pagination and Rate Limiting**\n\n* Material APIs use **cursor-based pagination**: you pass the `nextCursor` value from one response as the `cursor` parameter in the next request.\n* The `limit` parameter controls page size and is locked into the cursor, so later pages keep the page size of the first request.\n* Every paginated response includes a `meta` object with `limit`, `hasMore`, and `nextCursor` (`totalCount` isn't available for trusted entities).\n* When `hasMore` is false and `nextCursor` is null, you've reached the last page.\n"}],"servers":[{"url":"https://{domain}","description":"Material Security instance","variables":{"domain":{"default":"your-instance.on.material.security","description":"Your Material Security instance domain"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-material-client-secret","description":"Material Security API key"}},"schemas":{"CreateTrustedEntityBody":{"title":"CreateTrustedEntityBody","type":"object","properties":{"entity":{"description":"The domain, email address, or IP/CIDR to allowlist.","type":"string"},"type":{"description":"The kind of identity to allowlist: `external_domain`, `internal_domain`, `email_address`, or `ip_address`.","type":"string","enum":["external_domain","internal_domain","email_address","ip_address"]},"tenant":{"description":"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.","anyOf":[{"type":"string"},{"type":"null"}]},"enabled":{"description":"Whether the entry is active. Defaults to `true`.","default":true,"type":"boolean"},"subdomains":{"description":"Whether to also cover subdomains of the domain: `included` or `not_included`. Domain entities only; rejected for email address and IP entities.","type":"string","enum":["included","not_included"]},"emailThreatDetection":{"description":"The [email threat handling](https://docs.material.security/getting-started/fundamentals/detect/trusted-entities#settings-definitions) 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":"detect","type":"string","enum":["detect","ignore_mark_safe","ignore_dont_create_issues"]},"emailAuthentication":{"description":"The [email authentication handling](https://docs.material.security/getting-started/fundamentals/detect/trusted-entities#settings-definitions) for this entity: `enforced` (don't trust messages that fail authentication) or `ignored` (trust messages regardless of authentication). Defaults to `enforced`.","default":"enforced","type":"string","enum":["enforced","ignored"]},"fileDetection":{"description":"The [file detection handling](https://docs.material.security/getting-started/fundamentals/detect/trusted-entities#settings-definitions) 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.","type":"string","enum":["treat_as_internal","treat_as_external"]}},"required":["entity","type"]},"APITrustedEntity":{"title":"APITrustedEntity","description":"An organization-level allowlist entry (a domain, email address, or IP/CIDR) that tunes how Material treats mail and files from that identity.","type":"object","properties":{"id":{"description":"The encoded trusted-entity ID. Format: `te.1.<base64>`.","type":"string"},"entity":{"description":"The domain, email address, or IP/CIDR this entry allowlists.","type":"string"},"type":{"description":"The kind of identity this entry allowlists: `external_domain`, `internal_domain`, `email_address`, or `ip_address`.","type":"string","enum":["external_domain","internal_domain","email_address","ip_address"]},"tenant":{"description":"The encoded ID of the tenant this entry applies to. Format: `tnt.1.<base64>`. `null` means it applies globally across all tenants.","anyOf":[{"type":"string"},{"type":"null"}]},"enabled":{"description":"Whether this trusted entity is active.","type":"boolean"},"subdomains":{"description":"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.","anyOf":[{"type":"string","enum":["included","not_included"]},{"type":"null"}]},"emailThreatDetection":{"description":"The [email threat handling](https://docs.material.security/getting-started/fundamentals/detect/trusted-entities#settings-definitions) 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).","type":"string","enum":["detect","ignore_mark_safe","ignore_dont_create_issues"]},"emailAuthentication":{"description":"The [email authentication handling](https://docs.material.security/getting-started/fundamentals/detect/trusted-entities#settings-definitions) for this entity: `enforced` (don't trust messages that fail authentication) or `ignored` (trust messages regardless of authentication).","type":"string","enum":["enforced","ignored"]},"fileDetection":{"description":"The [file detection handling](https://docs.material.security/getting-started/fundamentals/detect/trusted-entities#settings-definitions) 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.","anyOf":[{"type":"string","enum":["treat_as_internal","treat_as_external"]},{"type":"null"}]},"updatedAt":{"description":"When the entry was last modified, in ISO 8601 format. `null` for system-managed entities.","anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedBy":{"description":"The encoded account ID of the last editor. Format: `acct.1.<base64>`. `null` for system-managed entities.","anyOf":[{"type":"string"},{"type":"null"}]},"timeline":{"description":"The change timeline for this entry. Populated only when `include=timeline`.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/CollectionMeta"},"items":{"type":"array","items":{"$ref":"#/components/schemas/APITrustedEntityTimelineEvent"}}},"required":["meta","items"]}},"required":["id","entity","type","tenant","enabled","subdomains","emailThreatDetection","emailAuthentication","fileDetection","updatedAt","updatedBy"]},"CollectionMeta":{"title":"CollectionMeta","type":"object","properties":{"totalCount":{"description":"The total number of items matching the query.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"description":"The page size used for this response.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hasMore":{"description":"True if more items exist beyond the current page; false otherwise.","type":"boolean"},"nextCursor":{"description":"The cursor to fetch the next page of results. Pass this value to the `cursor` query parameter. Null if no more pages exist.","anyOf":[{"type":"string"},{"type":"null"}]}}},"APITrustedEntityTimelineEvent":{"title":"APITrustedEntityTimelineEvent","type":"object","properties":{"type":{"description":"The timeline type: `created`, `comment`, or `setting_updated`.","type":"string"},"at":{"description":"When the event occurred, in ISO 8601 format. `null` for system events.","anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"actor":{"description":"The encoded account ID of the account that triggered the event. Format: `acct.1.<base64>`. `null` for system events.","anyOf":[{"type":"string"},{"type":"null"}]},"detail":{"description":"The comment text or the setting name that changed. `null` when neither applies.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","at","actor","detail"]},"ValidationErrorResponse":{"title":"Validation Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"},"validationFailures":{"description":"List of individual validation failures when request parameters fail schema validation.","type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["error"]},"ErrorResponse":{"title":"Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"}},"required":["error"]}}},"paths":{"/api/v1/trusted-entities":{"post":{"operationId":"createTrustedEntity","summary":"Create Trusted Entity","description":"Creates a trusted entity. `entity` and `type` are required; other settings default to the least-permissive values. Returns 200 with the created entity.","tags":["Trusted Entities"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTrustedEntityBody"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APITrustedEntity"}}}},"400":{"description":"Bad request: invalid parameters or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Unauthorized: missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: the API key doesn't have permission to perform this action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found: the requested resource doesn't exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get Trusted Entity

> Retrieves a single trusted entity by its encoded ID. Use \`include=timeline\` to pull the change timeline.

```json
{"openapi":"3.1.0","info":{"title":"Material Security API","version":"v1"},"tags":[{"name":"Trusted Entities","description":"**Overview**\n\nThe Trusted Entities API provides programmatic access to your organization's [trusted entities](https://docs.material.security/getting-started/fundamentals/detect/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.\n\nSix endpoints make up the Trusted Entities API:\n\n* **[List Trusted Entities](https://docs.material.security/reference/api-v1/trusted-entities#get-api-v1-trusted-entities)** (`GET /api/v1/trusted-entities`): filter and retrieve a paginated list of trusted entities\n* **[Get Trusted Entity](https://docs.material.security/reference/api-v1/trusted-entities#get-api-v1-trusted-entities-id)** (`GET /api/v1/trusted-entities/{id}`): retrieve a single trusted entity by its encoded ID\n* **[Create Trusted Entity](https://docs.material.security/reference/api-v1/trusted-entities#post-api-v1-trusted-entities)** (`POST /api/v1/trusted-entities`): create a new trusted entity\n* **[Update Trusted Entity](https://docs.material.security/reference/api-v1/trusted-entities#patch-api-v1-trusted-entities-id)** (`PATCH /api/v1/trusted-entities/{id}`): update the editable settings of an existing trusted entity\n* **[Delete Trusted Entity](https://docs.material.security/reference/api-v1/trusted-entities#delete-api-v1-trusted-entities-id)** (`DELETE /api/v1/trusted-entities/{id}`): delete a trusted entity\n* **[Bulk Trusted Entities](https://docs.material.security/reference/api-v1/trusted-entities#post-api-v1-trusted-entities-bulk)** (`POST /api/v1/trusted-entities/bulk`): apply up to 200 create, update, or delete operations in one request\n\n**Response Structure**\n\nList responses follow the standard two-part structure:\n\n* **`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.\n* **`items`**: an array of trusted entity objects.\n\nResults 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.\n\n**The `include` Parameter**\n\nBy 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).\n\n**Want a walkthrough?**\n\nReview [Hello World](https://docs.material.security/reference/api-v1/hello-world).\n\n**Pagination and Rate Limiting**\n\n* Material APIs use **cursor-based pagination**: you pass the `nextCursor` value from one response as the `cursor` parameter in the next request.\n* The `limit` parameter controls page size and is locked into the cursor, so later pages keep the page size of the first request.\n* Every paginated response includes a `meta` object with `limit`, `hasMore`, and `nextCursor` (`totalCount` isn't available for trusted entities).\n* When `hasMore` is false and `nextCursor` is null, you've reached the last page.\n"}],"servers":[{"url":"https://{domain}","description":"Material Security instance","variables":{"domain":{"default":"your-instance.on.material.security","description":"Your Material Security instance domain"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-material-client-secret","description":"Material Security API key"}},"schemas":{"APITrustedEntity":{"title":"APITrustedEntity","description":"An organization-level allowlist entry (a domain, email address, or IP/CIDR) that tunes how Material treats mail and files from that identity.","type":"object","properties":{"id":{"description":"The encoded trusted-entity ID. Format: `te.1.<base64>`.","type":"string"},"entity":{"description":"The domain, email address, or IP/CIDR this entry allowlists.","type":"string"},"type":{"description":"The kind of identity this entry allowlists: `external_domain`, `internal_domain`, `email_address`, or `ip_address`.","type":"string","enum":["external_domain","internal_domain","email_address","ip_address"]},"tenant":{"description":"The encoded ID of the tenant this entry applies to. Format: `tnt.1.<base64>`. `null` means it applies globally across all tenants.","anyOf":[{"type":"string"},{"type":"null"}]},"enabled":{"description":"Whether this trusted entity is active.","type":"boolean"},"subdomains":{"description":"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.","anyOf":[{"type":"string","enum":["included","not_included"]},{"type":"null"}]},"emailThreatDetection":{"description":"The [email threat handling](https://docs.material.security/getting-started/fundamentals/detect/trusted-entities#settings-definitions) 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).","type":"string","enum":["detect","ignore_mark_safe","ignore_dont_create_issues"]},"emailAuthentication":{"description":"The [email authentication handling](https://docs.material.security/getting-started/fundamentals/detect/trusted-entities#settings-definitions) for this entity: `enforced` (don't trust messages that fail authentication) or `ignored` (trust messages regardless of authentication).","type":"string","enum":["enforced","ignored"]},"fileDetection":{"description":"The [file detection handling](https://docs.material.security/getting-started/fundamentals/detect/trusted-entities#settings-definitions) 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.","anyOf":[{"type":"string","enum":["treat_as_internal","treat_as_external"]},{"type":"null"}]},"updatedAt":{"description":"When the entry was last modified, in ISO 8601 format. `null` for system-managed entities.","anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedBy":{"description":"The encoded account ID of the last editor. Format: `acct.1.<base64>`. `null` for system-managed entities.","anyOf":[{"type":"string"},{"type":"null"}]},"timeline":{"description":"The change timeline for this entry. Populated only when `include=timeline`.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/CollectionMeta"},"items":{"type":"array","items":{"$ref":"#/components/schemas/APITrustedEntityTimelineEvent"}}},"required":["meta","items"]}},"required":["id","entity","type","tenant","enabled","subdomains","emailThreatDetection","emailAuthentication","fileDetection","updatedAt","updatedBy"]},"CollectionMeta":{"title":"CollectionMeta","type":"object","properties":{"totalCount":{"description":"The total number of items matching the query.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"description":"The page size used for this response.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hasMore":{"description":"True if more items exist beyond the current page; false otherwise.","type":"boolean"},"nextCursor":{"description":"The cursor to fetch the next page of results. Pass this value to the `cursor` query parameter. Null if no more pages exist.","anyOf":[{"type":"string"},{"type":"null"}]}}},"APITrustedEntityTimelineEvent":{"title":"APITrustedEntityTimelineEvent","type":"object","properties":{"type":{"description":"The timeline type: `created`, `comment`, or `setting_updated`.","type":"string"},"at":{"description":"When the event occurred, in ISO 8601 format. `null` for system events.","anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"actor":{"description":"The encoded account ID of the account that triggered the event. Format: `acct.1.<base64>`. `null` for system events.","anyOf":[{"type":"string"},{"type":"null"}]},"detail":{"description":"The comment text or the setting name that changed. `null` when neither applies.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","at","actor","detail"]},"ValidationErrorResponse":{"title":"Validation Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"},"validationFailures":{"description":"List of individual validation failures when request parameters fail schema validation.","type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["error"]},"ErrorResponse":{"title":"Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"}},"required":["error"]}}},"paths":{"/api/v1/trusted-entities/{id}":{"get":{"operationId":"getTrustedEntity","summary":"Get Trusted Entity","description":"Retrieves a single trusted entity by its encoded ID. Use `include=timeline` to pull the change timeline.","tags":["Trusted Entities"],"parameters":[{"in":"path","name":"id","schema":{"description":"Encoded trusted-entity id. Format: `te.1.<base64>`.","type":"string","pattern":"^[a-z]{1,6}\\.[0-9]{1,2}\\.[A-Za-z0-9_-]+$"},"required":true,"description":"Encoded trusted-entity id. Format: `te.1.<base64>`."},{"in":"query","name":"include","schema":{"description":"Comma-separated includes. Supported: `timeline`.","type":"string"},"description":"Comma-separated includes. Supported: `timeline`."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APITrustedEntity"}}}},"400":{"description":"Bad request: invalid parameters or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Unauthorized: missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: the API key doesn't have permission to perform this action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found: the requested resource doesn't exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Delete Trusted Entity

> Deletes a trusted entity by its encoded ID. Auto-enrolled/system entities cannot be deleted. Returns 204 No Content.

```json
{"openapi":"3.1.0","info":{"title":"Material Security API","version":"v1"},"tags":[{"name":"Trusted Entities","description":"**Overview**\n\nThe Trusted Entities API provides programmatic access to your organization's [trusted entities](https://docs.material.security/getting-started/fundamentals/detect/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.\n\nSix endpoints make up the Trusted Entities API:\n\n* **[List Trusted Entities](https://docs.material.security/reference/api-v1/trusted-entities#get-api-v1-trusted-entities)** (`GET /api/v1/trusted-entities`): filter and retrieve a paginated list of trusted entities\n* **[Get Trusted Entity](https://docs.material.security/reference/api-v1/trusted-entities#get-api-v1-trusted-entities-id)** (`GET /api/v1/trusted-entities/{id}`): retrieve a single trusted entity by its encoded ID\n* **[Create Trusted Entity](https://docs.material.security/reference/api-v1/trusted-entities#post-api-v1-trusted-entities)** (`POST /api/v1/trusted-entities`): create a new trusted entity\n* **[Update Trusted Entity](https://docs.material.security/reference/api-v1/trusted-entities#patch-api-v1-trusted-entities-id)** (`PATCH /api/v1/trusted-entities/{id}`): update the editable settings of an existing trusted entity\n* **[Delete Trusted Entity](https://docs.material.security/reference/api-v1/trusted-entities#delete-api-v1-trusted-entities-id)** (`DELETE /api/v1/trusted-entities/{id}`): delete a trusted entity\n* **[Bulk Trusted Entities](https://docs.material.security/reference/api-v1/trusted-entities#post-api-v1-trusted-entities-bulk)** (`POST /api/v1/trusted-entities/bulk`): apply up to 200 create, update, or delete operations in one request\n\n**Response Structure**\n\nList responses follow the standard two-part structure:\n\n* **`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.\n* **`items`**: an array of trusted entity objects.\n\nResults 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.\n\n**The `include` Parameter**\n\nBy 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).\n\n**Want a walkthrough?**\n\nReview [Hello World](https://docs.material.security/reference/api-v1/hello-world).\n\n**Pagination and Rate Limiting**\n\n* Material APIs use **cursor-based pagination**: you pass the `nextCursor` value from one response as the `cursor` parameter in the next request.\n* The `limit` parameter controls page size and is locked into the cursor, so later pages keep the page size of the first request.\n* Every paginated response includes a `meta` object with `limit`, `hasMore`, and `nextCursor` (`totalCount` isn't available for trusted entities).\n* When `hasMore` is false and `nextCursor` is null, you've reached the last page.\n"}],"servers":[{"url":"https://{domain}","description":"Material Security instance","variables":{"domain":{"default":"your-instance.on.material.security","description":"Your Material Security instance domain"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-material-client-secret","description":"Material Security API key"}},"schemas":{"ValidationErrorResponse":{"title":"Validation Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"},"validationFailures":{"description":"List of individual validation failures when request parameters fail schema validation.","type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["error"]},"ErrorResponse":{"title":"Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"}},"required":["error"]}}},"paths":{"/api/v1/trusted-entities/{id}":{"delete":{"operationId":"deleteTrustedEntity","summary":"Delete Trusted Entity","description":"Deletes a trusted entity by its encoded ID. Auto-enrolled/system entities cannot be deleted. Returns 204 No Content.","tags":["Trusted Entities"],"parameters":[{"in":"path","name":"id","schema":{"description":"Encoded trusted-entity id. Format: `te.1.<base64>`.","type":"string","pattern":"^[a-z]{1,6}\\.[0-9]{1,2}\\.[A-Za-z0-9_-]+$"},"required":true,"description":"Encoded trusted-entity id. Format: `te.1.<base64>`."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"400":{"description":"Bad request: invalid parameters or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Unauthorized: missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: the API key doesn't have permission to perform this action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found: the requested resource doesn't exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Update Trusted Entity

> Updates the mutable settings of a trusted entity. \`entity\`, \`type\`, and \`tenant\` are immutable. Only provided fields change. Updating a system-managed entity (auto-enrolled or Material) creates a customization that overrides its default settings.

```json
{"openapi":"3.1.0","info":{"title":"Material Security API","version":"v1"},"tags":[{"name":"Trusted Entities","description":"**Overview**\n\nThe Trusted Entities API provides programmatic access to your organization's [trusted entities](https://docs.material.security/getting-started/fundamentals/detect/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.\n\nSix endpoints make up the Trusted Entities API:\n\n* **[List Trusted Entities](https://docs.material.security/reference/api-v1/trusted-entities#get-api-v1-trusted-entities)** (`GET /api/v1/trusted-entities`): filter and retrieve a paginated list of trusted entities\n* **[Get Trusted Entity](https://docs.material.security/reference/api-v1/trusted-entities#get-api-v1-trusted-entities-id)** (`GET /api/v1/trusted-entities/{id}`): retrieve a single trusted entity by its encoded ID\n* **[Create Trusted Entity](https://docs.material.security/reference/api-v1/trusted-entities#post-api-v1-trusted-entities)** (`POST /api/v1/trusted-entities`): create a new trusted entity\n* **[Update Trusted Entity](https://docs.material.security/reference/api-v1/trusted-entities#patch-api-v1-trusted-entities-id)** (`PATCH /api/v1/trusted-entities/{id}`): update the editable settings of an existing trusted entity\n* **[Delete Trusted Entity](https://docs.material.security/reference/api-v1/trusted-entities#delete-api-v1-trusted-entities-id)** (`DELETE /api/v1/trusted-entities/{id}`): delete a trusted entity\n* **[Bulk Trusted Entities](https://docs.material.security/reference/api-v1/trusted-entities#post-api-v1-trusted-entities-bulk)** (`POST /api/v1/trusted-entities/bulk`): apply up to 200 create, update, or delete operations in one request\n\n**Response Structure**\n\nList responses follow the standard two-part structure:\n\n* **`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.\n* **`items`**: an array of trusted entity objects.\n\nResults 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.\n\n**The `include` Parameter**\n\nBy 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).\n\n**Want a walkthrough?**\n\nReview [Hello World](https://docs.material.security/reference/api-v1/hello-world).\n\n**Pagination and Rate Limiting**\n\n* Material APIs use **cursor-based pagination**: you pass the `nextCursor` value from one response as the `cursor` parameter in the next request.\n* The `limit` parameter controls page size and is locked into the cursor, so later pages keep the page size of the first request.\n* Every paginated response includes a `meta` object with `limit`, `hasMore`, and `nextCursor` (`totalCount` isn't available for trusted entities).\n* When `hasMore` is false and `nextCursor` is null, you've reached the last page.\n"}],"servers":[{"url":"https://{domain}","description":"Material Security instance","variables":{"domain":{"default":"your-instance.on.material.security","description":"Your Material Security instance domain"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-material-client-secret","description":"Material Security API key"}},"schemas":{"UpdateTrustedEntityBody":{"title":"UpdateTrustedEntityBody","type":"object","properties":{"enabled":{"description":"Whether the entry is active.","type":"boolean"},"subdomains":{"description":"Whether to also cover subdomains of the domain: `included` or `not_included`. Domain entities only.","type":"string","enum":["included","not_included"]},"emailThreatDetection":{"description":"The [email threat handling](https://docs.material.security/getting-started/fundamentals/detect/trusted-entities#settings-definitions) 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).","type":"string","enum":["detect","ignore_mark_safe","ignore_dont_create_issues"]},"emailAuthentication":{"description":"The [email authentication handling](https://docs.material.security/getting-started/fundamentals/detect/trusted-entities#settings-definitions) for this entity: `enforced` (don't trust messages that fail authentication) or `ignored` (trust messages regardless of authentication).","type":"string","enum":["enforced","ignored"]},"fileDetection":{"description":"The [file detection handling](https://docs.material.security/getting-started/fundamentals/detect/trusted-entities#settings-definitions) for this entity: `treat_as_internal` (treat entity as internal) or `treat_as_external` (treat entity as external). Domain and email address entities only.","type":"string","enum":["treat_as_internal","treat_as_external"]}}},"APITrustedEntity":{"title":"APITrustedEntity","description":"An organization-level allowlist entry (a domain, email address, or IP/CIDR) that tunes how Material treats mail and files from that identity.","type":"object","properties":{"id":{"description":"The encoded trusted-entity ID. Format: `te.1.<base64>`.","type":"string"},"entity":{"description":"The domain, email address, or IP/CIDR this entry allowlists.","type":"string"},"type":{"description":"The kind of identity this entry allowlists: `external_domain`, `internal_domain`, `email_address`, or `ip_address`.","type":"string","enum":["external_domain","internal_domain","email_address","ip_address"]},"tenant":{"description":"The encoded ID of the tenant this entry applies to. Format: `tnt.1.<base64>`. `null` means it applies globally across all tenants.","anyOf":[{"type":"string"},{"type":"null"}]},"enabled":{"description":"Whether this trusted entity is active.","type":"boolean"},"subdomains":{"description":"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.","anyOf":[{"type":"string","enum":["included","not_included"]},{"type":"null"}]},"emailThreatDetection":{"description":"The [email threat handling](https://docs.material.security/getting-started/fundamentals/detect/trusted-entities#settings-definitions) 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).","type":"string","enum":["detect","ignore_mark_safe","ignore_dont_create_issues"]},"emailAuthentication":{"description":"The [email authentication handling](https://docs.material.security/getting-started/fundamentals/detect/trusted-entities#settings-definitions) for this entity: `enforced` (don't trust messages that fail authentication) or `ignored` (trust messages regardless of authentication).","type":"string","enum":["enforced","ignored"]},"fileDetection":{"description":"The [file detection handling](https://docs.material.security/getting-started/fundamentals/detect/trusted-entities#settings-definitions) 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.","anyOf":[{"type":"string","enum":["treat_as_internal","treat_as_external"]},{"type":"null"}]},"updatedAt":{"description":"When the entry was last modified, in ISO 8601 format. `null` for system-managed entities.","anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedBy":{"description":"The encoded account ID of the last editor. Format: `acct.1.<base64>`. `null` for system-managed entities.","anyOf":[{"type":"string"},{"type":"null"}]},"timeline":{"description":"The change timeline for this entry. Populated only when `include=timeline`.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/CollectionMeta"},"items":{"type":"array","items":{"$ref":"#/components/schemas/APITrustedEntityTimelineEvent"}}},"required":["meta","items"]}},"required":["id","entity","type","tenant","enabled","subdomains","emailThreatDetection","emailAuthentication","fileDetection","updatedAt","updatedBy"]},"CollectionMeta":{"title":"CollectionMeta","type":"object","properties":{"totalCount":{"description":"The total number of items matching the query.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"description":"The page size used for this response.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hasMore":{"description":"True if more items exist beyond the current page; false otherwise.","type":"boolean"},"nextCursor":{"description":"The cursor to fetch the next page of results. Pass this value to the `cursor` query parameter. Null if no more pages exist.","anyOf":[{"type":"string"},{"type":"null"}]}}},"APITrustedEntityTimelineEvent":{"title":"APITrustedEntityTimelineEvent","type":"object","properties":{"type":{"description":"The timeline type: `created`, `comment`, or `setting_updated`.","type":"string"},"at":{"description":"When the event occurred, in ISO 8601 format. `null` for system events.","anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"actor":{"description":"The encoded account ID of the account that triggered the event. Format: `acct.1.<base64>`. `null` for system events.","anyOf":[{"type":"string"},{"type":"null"}]},"detail":{"description":"The comment text or the setting name that changed. `null` when neither applies.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","at","actor","detail"]},"ValidationErrorResponse":{"title":"Validation Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"},"validationFailures":{"description":"List of individual validation failures when request parameters fail schema validation.","type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["error"]},"ErrorResponse":{"title":"Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"}},"required":["error"]}}},"paths":{"/api/v1/trusted-entities/{id}":{"patch":{"operationId":"patchTrustedEntity","summary":"Update Trusted Entity","description":"Updates the mutable settings of a trusted entity. `entity`, `type`, and `tenant` are immutable. Only provided fields change. Updating a system-managed entity (auto-enrolled or Material) creates a customization that overrides its default settings.","tags":["Trusted Entities"],"parameters":[{"in":"path","name":"id","schema":{"description":"Encoded trusted-entity id. Format: `te.1.<base64>`.","type":"string","pattern":"^[a-z]{1,6}\\.[0-9]{1,2}\\.[A-Za-z0-9_-]+$"},"required":true,"description":"Encoded trusted-entity id. Format: `te.1.<base64>`."}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTrustedEntityBody"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APITrustedEntity"}}}},"400":{"description":"Bad request: invalid parameters or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Unauthorized: missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: the API key doesn't have permission to perform this action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found: the requested resource doesn't exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Bulk Trusted Entities

> 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\[]\`.

```json
{"openapi":"3.1.0","info":{"title":"Material Security API","version":"v1"},"tags":[{"name":"Trusted Entities","description":"**Overview**\n\nThe Trusted Entities API provides programmatic access to your organization's [trusted entities](https://docs.material.security/getting-started/fundamentals/detect/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.\n\nSix endpoints make up the Trusted Entities API:\n\n* **[List Trusted Entities](https://docs.material.security/reference/api-v1/trusted-entities#get-api-v1-trusted-entities)** (`GET /api/v1/trusted-entities`): filter and retrieve a paginated list of trusted entities\n* **[Get Trusted Entity](https://docs.material.security/reference/api-v1/trusted-entities#get-api-v1-trusted-entities-id)** (`GET /api/v1/trusted-entities/{id}`): retrieve a single trusted entity by its encoded ID\n* **[Create Trusted Entity](https://docs.material.security/reference/api-v1/trusted-entities#post-api-v1-trusted-entities)** (`POST /api/v1/trusted-entities`): create a new trusted entity\n* **[Update Trusted Entity](https://docs.material.security/reference/api-v1/trusted-entities#patch-api-v1-trusted-entities-id)** (`PATCH /api/v1/trusted-entities/{id}`): update the editable settings of an existing trusted entity\n* **[Delete Trusted Entity](https://docs.material.security/reference/api-v1/trusted-entities#delete-api-v1-trusted-entities-id)** (`DELETE /api/v1/trusted-entities/{id}`): delete a trusted entity\n* **[Bulk Trusted Entities](https://docs.material.security/reference/api-v1/trusted-entities#post-api-v1-trusted-entities-bulk)** (`POST /api/v1/trusted-entities/bulk`): apply up to 200 create, update, or delete operations in one request\n\n**Response Structure**\n\nList responses follow the standard two-part structure:\n\n* **`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.\n* **`items`**: an array of trusted entity objects.\n\nResults 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.\n\n**The `include` Parameter**\n\nBy 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).\n\n**Want a walkthrough?**\n\nReview [Hello World](https://docs.material.security/reference/api-v1/hello-world).\n\n**Pagination and Rate Limiting**\n\n* Material APIs use **cursor-based pagination**: you pass the `nextCursor` value from one response as the `cursor` parameter in the next request.\n* The `limit` parameter controls page size and is locked into the cursor, so later pages keep the page size of the first request.\n* Every paginated response includes a `meta` object with `limit`, `hasMore`, and `nextCursor` (`totalCount` isn't available for trusted entities).\n* When `hasMore` is false and `nextCursor` is null, you've reached the last page.\n"}],"servers":[{"url":"https://{domain}","description":"Material Security instance","variables":{"domain":{"default":"your-instance.on.material.security","description":"Your Material Security instance domain"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-material-client-secret","description":"Material Security API key"}},"schemas":{"BulkTrustedEntitiesBody":{"title":"BulkTrustedEntitiesBody","type":"object","properties":{"operations":{"description":"Up to 200 operations, applied best-effort with per-item results.","minItems":1,"maxItems":200,"type":"array","items":{"oneOf":[{"description":"Create a new trusted entity.","type":"object","properties":{"method":{"type":"string","const":"create"},"body":{"$ref":"#/components/schemas/CreateTrustedEntityBody"}},"required":["method","body"]},{"description":"Update an existing trusted entity.","type":"object","properties":{"method":{"type":"string","const":"update"},"id":{"description":"Encoded trusted-entity id. Format: `te.1.<base64>`.","type":"string","pattern":"^[a-z]{1,6}\\.[0-9]{1,2}\\.[A-Za-z0-9_-]+$"},"body":{"$ref":"#/components/schemas/UpdateTrustedEntityBody"}},"required":["method","id","body"]},{"description":"Delete an existing trusted entity.","type":"object","properties":{"method":{"type":"string","const":"delete"},"id":{"description":"Encoded trusted-entity id. Format: `te.1.<base64>`.","type":"string","pattern":"^[a-z]{1,6}\\.[0-9]{1,2}\\.[A-Za-z0-9_-]+$"}},"required":["method","id"]}],"type":"object"}}},"required":["operations"]},"CreateTrustedEntityBody":{"title":"CreateTrustedEntityBody","type":"object","properties":{"entity":{"description":"The domain, email address, or IP/CIDR to allowlist.","type":"string"},"type":{"description":"The kind of identity to allowlist: `external_domain`, `internal_domain`, `email_address`, or `ip_address`.","type":"string","enum":["external_domain","internal_domain","email_address","ip_address"]},"tenant":{"description":"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.","anyOf":[{"type":"string"},{"type":"null"}]},"enabled":{"description":"Whether the entry is active. Defaults to `true`.","default":true,"type":"boolean"},"subdomains":{"description":"Whether to also cover subdomains of the domain: `included` or `not_included`. Domain entities only; rejected for email address and IP entities.","type":"string","enum":["included","not_included"]},"emailThreatDetection":{"description":"The [email threat handling](https://docs.material.security/getting-started/fundamentals/detect/trusted-entities#settings-definitions) 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":"detect","type":"string","enum":["detect","ignore_mark_safe","ignore_dont_create_issues"]},"emailAuthentication":{"description":"The [email authentication handling](https://docs.material.security/getting-started/fundamentals/detect/trusted-entities#settings-definitions) for this entity: `enforced` (don't trust messages that fail authentication) or `ignored` (trust messages regardless of authentication). Defaults to `enforced`.","default":"enforced","type":"string","enum":["enforced","ignored"]},"fileDetection":{"description":"The [file detection handling](https://docs.material.security/getting-started/fundamentals/detect/trusted-entities#settings-definitions) 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.","type":"string","enum":["treat_as_internal","treat_as_external"]}},"required":["entity","type"]},"UpdateTrustedEntityBody":{"title":"UpdateTrustedEntityBody","type":"object","properties":{"enabled":{"description":"Whether the entry is active.","type":"boolean"},"subdomains":{"description":"Whether to also cover subdomains of the domain: `included` or `not_included`. Domain entities only.","type":"string","enum":["included","not_included"]},"emailThreatDetection":{"description":"The [email threat handling](https://docs.material.security/getting-started/fundamentals/detect/trusted-entities#settings-definitions) 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).","type":"string","enum":["detect","ignore_mark_safe","ignore_dont_create_issues"]},"emailAuthentication":{"description":"The [email authentication handling](https://docs.material.security/getting-started/fundamentals/detect/trusted-entities#settings-definitions) for this entity: `enforced` (don't trust messages that fail authentication) or `ignored` (trust messages regardless of authentication).","type":"string","enum":["enforced","ignored"]},"fileDetection":{"description":"The [file detection handling](https://docs.material.security/getting-started/fundamentals/detect/trusted-entities#settings-definitions) for this entity: `treat_as_internal` (treat entity as internal) or `treat_as_external` (treat entity as external). Domain and email address entities only.","type":"string","enum":["treat_as_internal","treat_as_external"]}}},"BulkTrustedEntitiesResponse":{"title":"BulkTrustedEntitiesResponse","type":"object","properties":{"results":{"description":"Per-operation result, in the same order as the request.","type":"array","items":{"oneOf":[{"type":"object","properties":{"method":{"type":"string","enum":["create","update","delete"]},"status":{"type":"string","const":"ok"},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"id":{"type":"string"},"entity":{"$ref":"#/components/schemas/APITrustedEntity"}},"required":["method","status","index","id"]},{"type":"object","properties":{"method":{"type":"string","enum":["create","update","delete"]},"status":{"type":"string","const":"error"},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"error":{"type":"string"},"id":{"type":"string"}},"required":["method","status","index","error"]}],"type":"object"}},"meta":{"description":"Aggregate counts across all operations.","type":"object","properties":{"succeeded":{"description":"Number of operations that succeeded.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"failed":{"description":"Number of operations that failed.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["succeeded","failed"]}},"required":["results","meta"]},"APITrustedEntity":{"title":"APITrustedEntity","description":"An organization-level allowlist entry (a domain, email address, or IP/CIDR) that tunes how Material treats mail and files from that identity.","type":"object","properties":{"id":{"description":"The encoded trusted-entity ID. Format: `te.1.<base64>`.","type":"string"},"entity":{"description":"The domain, email address, or IP/CIDR this entry allowlists.","type":"string"},"type":{"description":"The kind of identity this entry allowlists: `external_domain`, `internal_domain`, `email_address`, or `ip_address`.","type":"string","enum":["external_domain","internal_domain","email_address","ip_address"]},"tenant":{"description":"The encoded ID of the tenant this entry applies to. Format: `tnt.1.<base64>`. `null` means it applies globally across all tenants.","anyOf":[{"type":"string"},{"type":"null"}]},"enabled":{"description":"Whether this trusted entity is active.","type":"boolean"},"subdomains":{"description":"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.","anyOf":[{"type":"string","enum":["included","not_included"]},{"type":"null"}]},"emailThreatDetection":{"description":"The [email threat handling](https://docs.material.security/getting-started/fundamentals/detect/trusted-entities#settings-definitions) 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).","type":"string","enum":["detect","ignore_mark_safe","ignore_dont_create_issues"]},"emailAuthentication":{"description":"The [email authentication handling](https://docs.material.security/getting-started/fundamentals/detect/trusted-entities#settings-definitions) for this entity: `enforced` (don't trust messages that fail authentication) or `ignored` (trust messages regardless of authentication).","type":"string","enum":["enforced","ignored"]},"fileDetection":{"description":"The [file detection handling](https://docs.material.security/getting-started/fundamentals/detect/trusted-entities#settings-definitions) 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.","anyOf":[{"type":"string","enum":["treat_as_internal","treat_as_external"]},{"type":"null"}]},"updatedAt":{"description":"When the entry was last modified, in ISO 8601 format. `null` for system-managed entities.","anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"updatedBy":{"description":"The encoded account ID of the last editor. Format: `acct.1.<base64>`. `null` for system-managed entities.","anyOf":[{"type":"string"},{"type":"null"}]},"timeline":{"description":"The change timeline for this entry. Populated only when `include=timeline`.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/CollectionMeta"},"items":{"type":"array","items":{"$ref":"#/components/schemas/APITrustedEntityTimelineEvent"}}},"required":["meta","items"]}},"required":["id","entity","type","tenant","enabled","subdomains","emailThreatDetection","emailAuthentication","fileDetection","updatedAt","updatedBy"]},"CollectionMeta":{"title":"CollectionMeta","type":"object","properties":{"totalCount":{"description":"The total number of items matching the query.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"description":"The page size used for this response.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hasMore":{"description":"True if more items exist beyond the current page; false otherwise.","type":"boolean"},"nextCursor":{"description":"The cursor to fetch the next page of results. Pass this value to the `cursor` query parameter. Null if no more pages exist.","anyOf":[{"type":"string"},{"type":"null"}]}}},"APITrustedEntityTimelineEvent":{"title":"APITrustedEntityTimelineEvent","type":"object","properties":{"type":{"description":"The timeline type: `created`, `comment`, or `setting_updated`.","type":"string"},"at":{"description":"When the event occurred, in ISO 8601 format. `null` for system events.","anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"actor":{"description":"The encoded account ID of the account that triggered the event. Format: `acct.1.<base64>`. `null` for system events.","anyOf":[{"type":"string"},{"type":"null"}]},"detail":{"description":"The comment text or the setting name that changed. `null` when neither applies.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["type","at","actor","detail"]},"ValidationErrorResponse":{"title":"Validation Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"},"validationFailures":{"description":"List of individual validation failures when request parameters fail schema validation.","type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["error"]},"ErrorResponse":{"title":"Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"}},"required":["error"]}}},"paths":{"/api/v1/trusted-entities/bulk":{"post":{"operationId":"bulkTrustedEntities","summary":"Bulk Trusted Entities","description":"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[]`.","tags":["Trusted Entities"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkTrustedEntitiesBody"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkTrustedEntitiesResponse"}}}},"400":{"description":"Bad request: invalid parameters or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Unauthorized: missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: the API key doesn't have permission to perform this action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found: the requested resource doesn't exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.material.security/reference/api-v1/trusted-entities.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.