Skip to main content

Overrides API

Endpoints for managing session-scoped policy overrides. Implements ADR-042.

Available on platform v7.1.0+. Requires an Evaluation or Enterprise license for create/revoke operations. Community tier gets read-only visibility via audit search.

POST /api/v1/overrides​

Create a session-scoped override.

Request body​

{
  "policy_id": "pol-sqli-detector",
  "policy_type": "static",
  "override_reason": "Debugging prod incident INC-4521",
  "tool_signature": "Bash",
  "ttl_seconds": 900
}
FieldTypeRequiredNotes
policy_idstringyesPolicy to override.
policy_typestringyesstatic or dynamic.
override_reasonstringyes1–500 chars. Free text. Mandatory per ADR-042.
tool_signaturestringnoScope override to a specific tool name. Omit for tool-agnostic scope.
ttl_secondsintnoRequested TTL. Clamped server-side. Default 3600 (60m), hard cap 86400 (24h), min 60 (1m).

Response (201)​

{
  "id": "ov-f3a81c-...",
  "policy_id": "pol-sqli-detector",
  "policy_type": "static",
  "expires_at": "2026-04-17T13:15:00Z",
  "ttl_seconds": 900,
  "requested_ttl": 900,
  "clamped": false,
  "created_at": "2026-04-17T13:00:00Z"
}

When TTL is clamped:

{
  "id": "ov-...",
  "ttl_seconds": 86400,
  "requested_ttl": 172800,
  "clamped": true,
  "clamped_reason": "exceeds_hard_cap"
}

Error responses​

StatusMeaning
400Missing policy_id, policy_type, or override_reason. Reason exceeds 500 chars.
401Auth failure
403Policy is critical-risk (not overridable). Or policy has allow_override=false. Or tier doesn't permit override creation.
404Policy not found

Critical-risk rejection is enforced at the database level via trigger — allow_override=true on a critical-risk policy is coerced to false at insert time, so the server will always return 403 regardless of any race.

GET /api/v1/overrides​

List active overrides scoped to the caller's tenant.

Query parameters​

NameTypeDescription
policy_idstringFilter to overrides for a specific policy.
include_revokedboolInclude revoked overrides in results. Default false.

Response (200)​

{
  "overrides": [
    {
      "id": "ov-...",
      "policy_id": "pol-sqli-detector",
      "policy_type": "static",
      "tenant_id": "tenant-x",
      "override_reason": "Debugging",
      "expires_at": "2026-04-17T13:15:00Z",
      "revoked_at": null,
      "created_at": "2026-04-17T13:00:00Z"
    }
  ],
  "count": 1
}

Requires X-Tenant-ID header (set automatically by the agent).

GET /api/v1/overrides/{id}​

Fetch a single override by ID.

Response (200)​

{
  "id": "ov-...",
  "policy_id": "pol-sqli-detector",
  "policy_type": "static",
  "tenant_id": "tenant-x",
  "organization_id": "org-y",
  "tool_signature": "Bash",
  "override_reason": "Debugging",
  "expires_at": "2026-04-17T13:15:00Z",
  "created_by": "[email protected]",
  "created_at": "2026-04-17T13:00:00Z",
  "revoked_at": null,
  "revoked_by": null
}

Error responses​

StatusMeaning
404Override not found

DELETE /api/v1/overrides/{id}​

Revoke an override. Next policy evaluation after the revocation does not consult it.

Response (200)​

{
  "id": "ov-...",
  "revoked_at": "2026-04-17T13:10:00Z"
}

Error responses​

StatusMeaning
404Override not found or already revoked

Emits an override_revoked audit event.

Audit events​

Every override lifecycle event writes an entry to the audit log with its own request_type:

EventWhen
override_createdSuccessful POST /api/v1/overrides
override_usedPolicy evaluation consumed an active override to flip a deny
override_expiredBackground cleanup detected TTL expiry
override_revokedSuccessful DELETE (user, admin, or policy-change-triggered)

Audit record policy_details includes: override_id, policy_ids, reason, ttl_seconds, requested_ttl, clamped, and for override_used: decision_id. Search for all events tied to one override:

curl -X POST /api/v1/audit/search \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d '{"override_id": "ov-f3a81c-..."}'

See also​

Last updated on