Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
This reference covers the standalone named-policy flow. Use ARM to manage policies and Rego, and the account's data-plane endpoint to evaluate them.
Prerequisites
Complete the quickstart for preview access, a serving account, and authoring and runtime permissions. The management examples use its resource variables and the scripts listed in the sample guide. Run the examples from the directory containing the management scripts.
Endpoints and versions
| Purpose | Endpoint | Version |
|---|---|---|
| Account and policy management | https://management.azure.com |
2026-11-15-preview |
| Evaluation | The serving Content Safety account's endpoint | 2026-10-15-preview |
The policy resources are:
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}
/providers/Microsoft.CognitiveServices/accounts/{accountName}
/raiRegos/{regoName}
/raiPolicies/{policyName}
The line breaks above are for readability. Each request uses a single resource path.
Create reusable Rego before the policy that references it. A Rego PUT body contains properties.encoding and properties.rego.
None means plain source; the contract also defines Base64. The examples use plain UTF-8 source.
A policy PUT body contains properties.format: "ACS", properties.acs, and properties.acsRegos. The inner manifest version is 0.4.0-alpha.1, not either API version.
Authentication and authorization
| Call | OAuth scope | Access |
|---|---|---|
| ARM | https://management.azure.com/.default |
Resource-management actions required for the account and child resources. |
| Unified Moderate | https://cognitiveservices.azure.com/.default |
Cognitive Services User on the serving account, with preview access enabled. |
| Customer-owned judge inference | The supported model service audience, acquired by the service | Inference permission for the serving account identity on the model account. |
Use a custom-subdomain endpoint for Microsoft Entra authentication. Do not interchange ARM and data-plane tokens.
The data-plane contract also declares Ocp-Apim-Subscription-Key authentication, subject to the account's local-authentication and preview configuration. These guides use Entra credentials and recommend managed identities for applications. A subscription key is not a separate application identity.
Agent IDs, actor metadata, session IDs, and customer-provided identity claims in JSON are not authorization.
Use a managed identity in production
The quickstart uses an interactive developer identity. For an application, use a managed identity attached to its compute:
- Create or enable the identity on the application host.
- Grant its principal
Cognitive Services Useron the serving Content Safety account. - Configure the application's credential to select that identity and obtain a token for
https://cognitiveservices.azure.com/.default. - Verify that an authorized request succeeds and an unauthorized identity is rejected.
For a user-assigned identity, role assignments use its principal ID and principal type ServicePrincipal. Credential selection uses its client ID. Creating the identity without attaching it to the application host does not make it available to the application.
The application's identity is separate from the serving account identity used by a customer-owned LLM judge.
Call Unified Moderate
This HTTP request is schematic. {unified-moderate-url} includes your endpoint, /contentsafety/content:unifiedModerate, api-version=2026-10-15-preview, and the full ARM policyId, URL-encoded once.
POST {unified-moderate-url}
Authorization: Bearer <access-token>
Content-Type: application/json
Use the full ARM policy resource ID under the serving account as policyId. Where a deployment supports short policy names, the full ID is still the clearer selector. URL-encode it once using an HTTP query builder; do not manually concatenate unescaped IDs.
The standalone selector is a query parameter. No resource binding or additional resource selector is required.
Request body
This example evaluates tool arguments before dispatch:
{
"spec": "agent-hooks/0.1",
"interception_point": "pre_tool_call",
"timestamp": "2026-11-04T12:00:00Z",
"sequence": 2,
"agent": { "id": "support-agent", "framework": "custom" },
"session": { "id": "sample-tool" },
"tool_call": {
"id": "refund-1",
"name": "refund_order",
"args": { "order_id": "demo-001", "amount": 100 }
},
"target": { "order_id": "demo-001", "amount": 100 }
}
For actual execution, use a current timestamp, your session's ID and increasing sequence number, and the exact action your host is about to perform. The service validates the point-specific payload and target equality.
Keep values as native JSON. A tool argument object must not be encoded as a JSON string. Preserve numbers, booleans, arrays, objects, and null where the contract permits them.
The target mapping is listed in Author policies. SDK context builders help keep these fields consistent.
Limits
Requests and responses are each limited to 1,048,576 decoded UTF-8 JSON bytes and container depth 64, including the root. Use valid Unicode and unambiguous JSON member names. Duplicate members, conflicting selectors, and over-limit requests are errors, not truncated successful evaluations.
A supported HTTP payload size does not guarantee that a particular classifier or model can inspect that amount of content. Required capabilities have their own input and execution limits.
ARM authoring limits
Stored policy artifacts have separate limits from the runtime context:
| Item | Limit on enabled preview accounts | Measurement |
|---|---|---|
| ACS manifest | 256 KiB (262,144 bytes) | Compact serialized UTF-8 JSON for properties.acs. |
| Rego resource | 512 KiB (524,288 bytes) | Decoded UTF-8 source, including when uploaded with encoding: "Base64". |
| Complete ARM PUT body | 1 MiB (1,048,576 bytes) | The entire request body, including JSON wrappers and encoded source. |
These limits depend on the preview deployment. Some deployments enforce 48 KiB manifests and 200 KiB decoded Rego. Confirm the limits enabled for your account before relying on the larger caps.
Both artifact and whole-request limits apply. Base64 expands the transported source, and plain-source JSON escaping also contributes to body size. A request smaller than 1 MiB can still exceed the manifest or decoded-Rego limit.
Interpret the response
A successful response contains:
| Member | Meaning |
|---|---|
verdict |
The aggregate allow, deny, or transform decision. |
receipt |
Metadata identifying the evaluation and exact evaluated request and policies. |
HTTP 200 means evaluation completed. It does not mean the action is allowed.
For example, the verdict member can be:
{
"decision": "deny",
"reason": "tool_request_not_permitted",
"message": "Use approved tools. Refund amounts must be numeric: >0 and <=100."
}
The host must:
- Validate the response and receipt.
- Stop on
deny, malformed data, or operational failure. - Apply and validate a supported
transformbefore using its replacement value. - Execute or release only the evaluated, permitted value.
- Record what actually happened.
Startup and shutdown transforms are unsupported. The judge path in these guides also does not support transform verdicts. If your application cannot implement a returned transformation or approval workflow safely, keep the action blocked.
Approval requests
A review decision is a deny until your host resolves it. A policy can return, for example:
{
"decision": "deny",
"reason": "human_review_required",
"approval": {
"workflow": "transaction-review"
}
}
The approval object's contents must match a workflow your application implements; this example does not provision one. Bind any approval to the exact action and evaluated values. Do not treat the presence of approval as permission to execute, and do not let an approval override an independent unconditional deny.
The approval field does not open a review queue or grant permission.
Receipt fields
| Field | Host check or use |
|---|---|
receiptVersion |
Match the transport contract, here 2026-10-15-preview. |
profile |
Expect namedPolicy for this flow. |
evaluationId, attempt |
Correlate service evaluation and host execution records. |
requestBinding |
Require algorithm: "sha256" and canonicalization: "rfc8785", then compare digest with the hash of the exact request material below. |
evaluatedPolicyLayers |
Verify the expected named policy; retain its revision, semantic digest, activated artifact digest, and decision. |
evaluatedInterventionPoint |
Match the point sent in this request. |
requiredInterventionPoints |
Check that your host implements every required point. This does not prove that the host called them. |
hostProfileVersion |
Record the service evaluation profile. |
authenticatedProducerResourceId |
For this namedPolicy flow, match the serving account ID from trusted configuration, not a value copied from the response. |
harmResults, when present |
Public classifier summaries, not the Rego input or complete internal model diagnostics. |
For example, a complete named-policy deny response has this shape. The resource IDs, revision, evaluation ID, and digests are illustrative placeholders, not values to copy into a validator. Real policyResourceId and authenticatedProducerResourceId values are full ARM IDs for the policy and serving account, respectively:
{
"verdict": { "decision": "deny", "reason": "refund_not_permitted" },
"receipt": {
"receiptVersion": "2026-10-15-preview",
"profile": "namedPolicy",
"evaluationId": "evaluation-<unique-id>",
"attempt": 1,
"requestBinding": {
"algorithm": "sha256",
"canonicalization": "rfc8785",
"digest": "sha256:<request-digest>"
},
"evaluatedPolicyLayers": [
{
"kind": "namedPolicy",
"policyResourceId": "<full-policy-resource-id>",
"policyRevision": "<policy-revision>",
"policySemanticDigest": "sha256:<semantic-digest>",
"manifestRegoDigest": "sha256:<artifact-digest>",
"decision": "deny"
}
],
"evaluatedInterventionPoint": "pre_tool_call",
"requiredInterventionPoints": ["pre_tool_call"],
"hostProfileVersion": "<host-profile-version>",
"authenticatedProducerResourceId": "<serving-account-resource-id>"
}
}
Each real digest contains sha256: followed by 64 lowercase hexadecimal characters. evaluatedPolicyLayers can contain additional applicable layers; do not assume there is always exactly one. Verify the selected named policy is present, preserve the other layers, and enforce the aggregate verdict rather than an individual layer's allow.
The request-binding digest is the SHA-256 hash of RFC 8785 canonical UTF-8 JSON for:
{
"apiVersion": <the exact Unified Moderate API version>,
"context": <the exact decoded request body>,
"selectors": { "policyId": <the exact accepted selector value> }
}
The digest string is prefixed with sha256:. Use a canonicalization library rather than assuming ordinary JSON serialization has the required order and number representation. The sample client implements this check.
The digest binds evaluation metadata to a request; it is not a receipt signature or proof that a tool executed. Keep it with a separate host outcome.
Handle errors
| HTTP status or condition | Action |
|---|---|
400, InvalidRequest |
Correct the context, JSON types, point/target pairing, selector, or payload size. |
401 |
Check credential acquisition, token audience, and expiration. |
403 |
Check the selected caller's data-plane role, account scope, preview access, and policy authorization. |
404, NativeRouteDisabled |
Check endpoint, API version, account, and region enablement. Do not change to an older request format as an automatic fallback. |
409, PolicyFenceChanged |
The policy changed during evaluation. Reconcile the intended version before a bounded retry. |
UnsupportedCapability or unavailable required policy/dependency |
Restore the required capability or policy. Do not skip its check. |
429 |
Honor Retry-After when supplied and reduce load. Keep the action blocked. |
500, 503, transport error, or timeout |
Keep the action blocked. Retry only within a bounded application deadline. |
200 with deny |
A policy outcome, not a transport failure. Do not retry until it becomes an allow. |
| Invalid verdict or receipt mismatch | Do not act. Record the failure and investigate. |
Operational error codes can differ between serving configurations. Preserve the actual returned code, HTTP status, and request/evaluation correlation information without logging sensitive payloads.
Retries and quotas
A single evaluation can invoke multiple required detectors or judges. Account limits and model-deployment limits are separate; an evaluation's HTTP request count does not establish its internal detector or inference usage.
Use the quotas assigned to your enabled account and model deployment when setting concurrency. Do not assume a universal requests-per-second limit from this guide.
An evaluation retry is not permission to retry a non-idempotent tool action. Keep the original action pending, bound retries by time and count, and prevent duplicate dispatch. Do not reuse a previous allow for changed arguments, changed output, a different lifecycle point, or a later action.
Update and roll out policies
Publish new named policy versions for a staged rollout. Use conditional replacement only when you intentionally update an existing resource.
Prefer a new named version
Create a new policy and Rego resource with a new name, test it, and deliberately change the application's configured selector. For example, use publish-policy.ps1:
$Candidate = .\publish-policy.ps1 -AccountId $AccountId `
-TemplateDirectory .\refund-guard -PolicyName 'refund-guard-v2'
Keep the previous version available during rollout. Moving the selector back is a configuration rollback; it does not undo actions already executed.
Conditional in-place replacement
If you intentionally replace a policy, GET its current ETag and use If-Match. The following example uses arm.ps1:
. .\arm.ps1
$Current = Invoke-AgentControlArm -Method GET -ResourceId $PolicyId
if (-not $Current.ETag) { throw 'The current policy has no ETag.' }
$Replacement = Get-Content .\refund-guard\policy.json -Raw |
ConvertFrom-Json -AsHashtable
# Preserve or deliberately change the same-account Rego references.
$Replacement.properties.acsRegos[0].regoName = '<intended-existing-Rego-name>'
$Updated = Invoke-AgentControlArm -Method PUT -ResourceId $PolicyId `
-Headers @{ 'If-Match' = $Current.ETag } -Body $Replacement
Use an accepted request body, not the complete GET response with read-only fields. A precondition failure requires review and reconciliation; do not retry an unconditional overwrite.
Changes to reusable Rego can affect policies that reference it. Publishing new named source and policy resources avoids treating multi-resource updates as an atomic operation.
Named-policy calls select the authorized policy by ID; the request format shown here does not pin an ETag. Use distinct named versions for deliberate rollout, and record the actual revision returned in each receipt.
Monitor evaluation and enforcement
Record:
- Session, action, point, and evaluation IDs.
- Policy resource IDs, revisions, and digests.
- Decision and reason, including unresolved approvals.
- Service latency, timeouts, failures, and throttling.
- Whether the action was blocked, dispatched, transformed, or released.
A useful host assertion is zero protected dispatches or releases after deny/error. Check point coverage as well; perfect response handling does not protect an action that never called the service.
Avoid raw prompts, tool arguments, model output, access tokens, and judge rubrics in routine logs. Receipt metadata is useful for correlation, but it does not replace a data-handling policy.
Delete a policy and its Rego
- Stop or reconfigure clients using the policy.
- Check for other references to its reusable Rego.
- Delete the policy with its current ETag.
- If deletion is asynchronous, wait for the ARM operation to succeed.
- Delete Rego only after it is no longer referenced.
For resources created by the publishing script:
.\remove-policy.ps1 -PolicyId $Published.PolicyId -RegoId $Published.RegoId
The remove-policy.ps1 script checks that both IDs belong to the same account, uses ETags, waits for asynchronous operations, and deletes only those two resources. A conflict or failed deletion is an error; it does not proceed by force.
The script does not delete the serving account, model account, role assignments, or resource group. Review and remove unused resources separately.