Policies

Endpoint reference for access policies. For the guide, see Policies. For the model, see Policies and Permissions.

Base path: /v1/policies/

GET /v1/policies#

List policies.

Query: scope (tenant|partner), include_inactive, limit, cursor.

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "policies": [
    {
      "id": "pol_abc",
      "name": "production-read-only",
      "rule_count": 2,
      "binding_count": 5,
      "is_active": true,
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-15T00:00:00Z"
    }
  ],
  "cursor": null,
  "has_more": false
}

Scope: policies:read.

POST /v1/policies#

Create.

Body:

Response 201 Created: full policy object.

Scope: policies:write.

GET /v1/policies/{id}#

Get one policy, including rules and bindings.

Scope: policies:read.

PUT /v1/policies/{id}#

Replace policy (rules + metadata). Bindings preserved.

Scope: policies:write.

PATCH /v1/policies/{id}#

Partial update (only provided fields).

Scope: policies:write.

DELETE /v1/policies/{id}#

Delete. Returns 409 policy_in_use if bindings exist. Add ?force=true to remove them.

Scope: policies:write.

GET /v1/policies/{id}/bindings#

List bindings for a policy.

Scope: policies:read.

POST /v1/policies/{id}/bindings#

Create binding.

Body:

Response 201 Created.

Scope: policies:write.

DELETE /v1/policies/{id}/bindings/{binding_id}#

Remove binding.

Scope: policies:write.

POST /v1/policies/test#

Dry-run access check. Does not write audit.

Body:

Response:

1
2
3
4
5

{
  "allowed": true,
  "matching_policies": [{"id": "pol_abc", "name": "...", "matching_rule_index": 0}],
  "evaluated_at": "2026-04-23T..."
}

On deny:

1
2
3
4
5
6

{
  "allowed": false,
  "reason": "condition_failed",
  "failed_condition": "require_mfa",
  "matching_rule": {"policy_id": "pol_abc", "rule_index": 0}
}

Scope: policies:read.

Permissions#

Conditions#

Related#

• Policies
• Policies and Permissions