Skip to Content
Policies

Update policy

Update an existing policy. Set placement to move it in the same call.

PATCH
/policies/{policy_id}

Update an existing policy. Set placement to move it in the same call.

Authorization

ApiKeyAuth
headerAuthorizationBearer <token>

Bearer token authentication. Send an API key (a saai_api_-prefixed token) as Authorization: Bearer <token>.

Required permission

manage_policies

Path Parameters

policy_id*string
Formatuuid

Request Body

application/json
  1. body

Fields that may be changed on an existing policy. Scope fields sent replace the stored ones; omitted fields keep their value.

placement?

Where to put the rule. On create, omit it for the default: a deny goes to the top, any other rule to the bottom. On update, omit it to keep the current position.

scope?||

Which calls a policy governs. A tool rule must name its tools in tool_patterns or tool_tag_ids; a model rule must name its models in model_patterns; a model route must name its model_patterns.

effect?PolicyEffect

Whether a matching rule permits, blocks, gates, or routes the call.

Value in"allow""deny""require_approval""route"
status?RuleStatus

Whether a rule takes part in evaluation.

Value in"active""draft""disabled"
approval_grace_seconds?|

How long one approval stays reusable for later calls this rule matches, in seconds. Null uses the default. Only meaningful with the require_approval effect.

Range0 <= value
approval_scope?|

Which later calls one approval covers during its grace window. Null uses identical_call. Only meaningful with the require_approval effect, and ignored when the grace is 0.

route_targets?array<>|

Where calls this route matches run: exactly one target today. Model routes only.

Items1 <= items <= 1
name?string

Short label for the rule, shown in the policy list.

description?|

Optional note explaining the rule's intent.

Response Body

The request has succeeded.

application/json
  1. response

One rule in an ordered list, for which agents and users and under what conditions. Tool and model rules decide what may run, and a request that matches none of them is denied by default; a model route decides where a model call runs, and a call that matches no route runs as requested. Rules are evaluated top to bottom and the first match wins.

id*uuid
Formatuuid
priority*integer

Position in the evaluation order: lower numbers are checked first. Set it with placement on create or update.

Formatint32
scope*||

Which calls a policy governs. A tool rule must name its tools in tool_patterns or tool_tag_ids; a model rule must name its models in model_patterns; a model route must name its model_patterns.

effect*PolicyEffect

Whether a matching rule permits, blocks, gates, or routes the call.

Value in"allow""deny""require_approval""route"
status?RuleStatus

Whether a rule takes part in evaluation.

Value in"active""draft""disabled"
approval_grace_seconds?|

How long one approval stays reusable for later calls this rule matches, in seconds. Null uses the default. Only meaningful with the require_approval effect.

Range0 <= value
approval_scope?|

Which later calls one approval covers during its grace window. Null uses identical_call. Only meaningful with the require_approval effect, and ignored when the grace is 0.

route_targets?array<>|

Where calls this route matches run: exactly one target today. Model routes only.

Items1 <= items <= 1
name*string

Short label for the rule, shown in the policy list.

description?|

Optional note explaining the rule's intent.

agent_instance_refs?array<>

Running agent instances this rule's scope currently resolves to.

user_refs?array<>

Users this rule's scope currently resolves to.

created_at*string
Formatdate-time
updated_at*string
Formatdate-time
Example Request
curl -X PATCH 'https://your-org.aisecurity.services.us.connect.secureauth.com/api/v1/policies/497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "priority": 0,  "scope": {    "type": "mcp_call",    "agent_slugs": [      "string"    ],    "agent_instance_ids": [      "bc3f18ff-0dcd-4cc7-8f61-6ca61814f10b"    ],    "user_ids": [      "2d98503d-4ab4-41bd-8fc6-78cc006fd2db"    ],    "groups": [      "string"    ],    "agent_slug_tag_ids": [      "e428595a-d9dd-4887-8327-2d9cad5b7425"    ],    "autonomous": true,    "mcp_ids": [      "c2c9208c-a7ac-41cc-84f1-8c1caec92987"    ],    "mcp_tag_ids": [      "17d4a46c-d971-4171-9a66-88ec59ce6eeb"    ],    "tool_tag_ids": [      "41068329-9b4f-4cc3-b249-3ec2a7a2cee8"    ],    "tool_patterns": [      "string"    ],    "condition": "string",    "condition_description": "string"  },  "effect": "allow",  "status": "active",  "approval_grace_seconds": 0,  "approval_scope": "identical_call",  "route_targets": [    {      "model": "string",      "model_provider_id": "e8dd39c4-1070-4c00-8ab5-c345bdef77c9"    }  ],  "name": "string",  "description": "string",  "agent_instance_refs": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "display_name": "string",      "user_display_name": "string"    }  ],  "user_refs": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "display_name": "string"    }  ],  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}