teamsProtectionPolicy

Teams Protection Policies. Defender policy protecting Microsoft Teams chats from malicious content. The teamsProtectionPolicy singleton lives under /exchange/v1.0/teamsProtectionPolicy in the Threat protection category.

Fact	Value
Path	`/exchange/v1.0/teamsProtectionPolicy`
Category	Threat protection
Tier	Tier 4, Threat protection
Read role	`ThreatPolicy.Read.All` (Community)
Write role	`ThreatPolicy.ReadWrite.All` (Enterprise)
Backing cmdlets	Get-TeamsProtectionPolicy, Set-TeamsProtectionPolicy, New-TeamsProtectionPolicy

Routes

Method	Path	Synopsis	Role	Plan
GET	`/exchange/v1.0/teamsProtectionPolicy`	Read the teamsProtectionPolicy singleton.	`ThreatPolicy.Read`	Community
POST	`/exchange/v1.0/teamsProtectionPolicy`	POST /teamsProtectionPolicy - provision-if-absent via New-TeamsProtectionPolicy. Required: name.	`ThreatPolicy.ReadWrite`	Enterprise
PATCH	`/exchange/v1.0/teamsProtectionPolicy`	Partial update via Set-TeamsProtectionPolicy (singleton - no URL key).	`ThreatPolicy.ReadWrite`	Enterprise

GET /exchange/v1.0/teamsProtectionPolicy

Read the teamsProtectionPolicy singleton.

Backing cmdlet: Get-TeamsProtectionPolicy. Role: ThreatPolicy.Read (Community).

List teamsProtectionPolicy

Stub auto-generated example for the teamsProtectionPolicy collection. Backing cmdlet: Get-TeamsProtectionPolicy. Live-verify with ?$top=3&$select=Id,Name and replace the synthetic body before promoting to Tier 1.

GET /exchange/v1.0/teamsProtectionPolicy?$top=3 HTTP/1.1
Authorization: Bearer {token}

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#teamsProtectionPolicy",
  "value": []
}

Notes: Illustrative example derived from the cmdlet documentation, not a live capture: field names are real, values are placeholders.

POST /exchange/v1.0/teamsProtectionPolicy

POST /teamsProtectionPolicy - provision-if-absent via New-TeamsProtectionPolicy. Required: name.

This is a singleton entity (isSingleton: true in EntityCatalog; keyless GET + PATCH). The POST is intentionally retained as a provision-if-absent action: a tenant has at most one “Teams Protection Policy”, so most callers only ever PATCH (Set). New is for the case where the tenant has none yet. No Remove cmdlet exists. (Audit 2026-06-01 RS-1 - owner decision: keep the POST rather than model as a strict no-POST singleton.)

Backing cmdlet: New-TeamsProtectionPolicy. Role: ThreatPolicy.ReadWrite (Enterprise).

Parameter	In	Type	Required
`name`	body		yes
`highConfidencePhishQuarantineTag`	body
`malwareQuarantineTag`	body
`zapEnabled`	body
`dryRun`	query	bool (switch)

Create rejected - required name missing

New-TeamsProtectionPolicy requires a name. Omitting it returns a 400 BadRequest from the body validator before the cmdlet is invoked.

POST /exchange/v1.0/teamsProtectionPolicy HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

{
  "zapEnabled": true
}

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "code": "BadRequest",
    "message": "The required field 'name' is missing or empty.",
    "target": "name"
  },
  "correlationId": "0HN7K3M4P5Q6R-00000001"
}

Notes: Doc-derived from Wiki + write-param allowlist; not live-captured. Body fields are Wiki-valid; values are illustrative.

Create a Teams protection policy

Create the Teams protection policy singleton via New-TeamsProtectionPolicy. Most tenants already have a single “Teams Protection Policy” and will only Set it; New is used when no policy exists yet.

POST /exchange/v1.0/teamsProtectionPolicy HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "exonaut-sample-teamsProtectionPolicy",
  "zapEnabled": true,
  "highConfidencePhishQuarantineTag": "AdminOnlyAccessPolicy",
  "malwareQuarantineTag": "AdminOnlyAccessPolicy"
}

HTTP/1.1 201 Created
Location: /exchange/v1.0/teamsProtectionPolicy/exonaut-sample-teamsProtectionPolicy

{
  "Id": "exonaut-sample-teamsProtectionPolicy",
  "Identity": "exonaut-sample-teamsProtectionPolicy",
  "Name": "exonaut-sample-teamsProtectionPolicy",
  "ZapEnabled": true,
  "HighConfidencePhishQuarantineTag": "AdminOnlyAccessPolicy",
  "MalwareQuarantineTag": "AdminOnlyAccessPolicy"
}

Notes: Doc-derived from Wiki + write-param allowlist; not live-captured. Body fields are Wiki-valid; values are illustrative.

PATCH /exchange/v1.0/teamsProtectionPolicy

Partial update via Set-TeamsProtectionPolicy (singleton - no URL key).

Backing cmdlet: Set-TeamsProtectionPolicy. Role: ThreatPolicy.ReadWrite (Enterprise).

Parameter	In	Type
`adminDisplayName`	body
`highConfidencePhishQuarantineTag`	body
`malwareQuarantineTag`	body
`zapEnabled`	body
`dryRun`	query	bool (switch)

Update the Teams protection policy

Partial update of the Teams protection policy singleton via Set-TeamsProtectionPolicy. No URL key - the policy is a singleton. Returns the updated entity.

PATCH /exchange/v1.0/teamsProtectionPolicy HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

{
  "zapEnabled": true,
  "adminDisplayName": "Updated by EXONAUT automation",
  "highConfidencePhishQuarantineTag": "AdminOnlyAccessPolicy"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "Id": "Teams Protection Policy",
  "Identity": "Teams Protection Policy",
  "Name": "Teams Protection Policy",
  "ZapEnabled": true,
  "AdminDisplayName": "Updated by EXONAUT automation",
  "HighConfidencePhishQuarantineTag": "AdminOnlyAccessPolicy"
}

Notes: Doc-derived from Wiki + write-param allowlist; not live-captured. Body fields are Wiki-valid; values are illustrative.

?dryRun=true previews of any write stay on Community.