Replace the policy

OpenAPI protocol version: 1.0.0.

Source operation metadata · Source value schemas

Compile and replace the complete policy. A compilation failure leaves the previous policy active. Replacement updates policy-declared facts and preserves facts inserted through the API. The response has no body.

Paths are relative to your instance URL. JSON request bodies require Content-Type: application/json.

Request parameters

Name	Location	Required	Description
Idempotency-Key	header	No	Optional key for one logical mutation. Repeat the same key and payload to replay its retained result; a different payload conflicts. Receipts are retained for 60 seconds. Policy and fact mutations use separate key scopes. Do not assume a retry after retention expires is deduplicated.

Idempotency-Key schema

string

Minimum length: 1 characterMaximum length: 128 characters

View JSON Schema

{
  "type": "string",
  "minLength": 1,
  "maxLength": 128
}

Deployment request headers

Header	Behavior
Authorization	Bearer API key for Cloud instances and Node servers configured with API keys. Node servers without API keys do not require this header.
Verdict-Session-Id	Cloud replica-selection affinity identifier, 1 to 128 ASCII letters, digits, underscores, or hyphens. This is not an authentication credential. Node servers do not interpret it.

Request body

Example body

{
  "source": "allow(User:alice, \"read\", Document:guide);"
}

Fields

sourcestringrequired

View JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": [
    "source"
  ],
  "properties": {
    "source": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

Responses

See common status codes and error bodies. Success responses and operation-specific exceptions are listed here.

Status	Meaning
204	Mutation applied; no response body
422	Policy compilation failed

Successful response header Verdict-Revision: Observed revision token on successful Cloud and replicated Node responses. Absent on standalone Node servers. Preserve the token unchanged for a minimum-revision read.

422 JSON body

errorstringrequired

messagestringrequired

View JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": [
    "error",
    "message"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "additionalProperties": false
}