OS protection gate
Effective org policy for overriding failing OS protection checks, and the audit event clients send when an override is granted or revoked.
Two endpoints back the OS protection gate. Both take a codai_ API key as a Bearer token.
GET /v1/policy returns { "os_gate": { "allow_override": boolean } }, folded over every organization you belong to: if any of them forbids overrides the answer is false. The response is Cache-Control: private, max-age=300; clients cache it and keep the last value offline. A database outage is a 503 policy_unavailable — keep the cached value, never assume a permissive default.
POST /v1/os-gate/events records a grant or revoke in your account audit log (os_gate.override). The strict body carries only action, checks (1 to 16 known check ids), surface, app_version and at; no detection details. It answers 202 { "ok": true }.
The same operations are in the SDKs: client.osGate.policy() / client.osGate.recordEvent(event) in TypeScript and client.os_gate.policy() / client.os_gate.record_event(...) in Python. The MCP server exposes the policy as the read-only os_gate_policy tool (account toolset); the audit event is device telemetry and has no MCP tool.
bearerAuthAuthorizationBearer <codai_…>A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).
x-request-id?stringClient correlation id; echoed back as x-codai-trace-id and persisted on the usage row.
length <= 128The effective policy for the caller.
application/json- response
os_gate*curl -X GET 'https://ai.codai.ro/v1/policy'{ "os_gate": { "allow_override": true }}bearerAuthAuthorizationBearer <codai_…>A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).
x-request-id?stringClient correlation id; echoed back as x-codai-trace-id and persisted on the usage row.
length <= 128The override event as recorded on the device.
application/json- body
action*stringWhether the user granted or revoked the override.
"granted""revoked"checks*array<>Ids of the checks the override covers (spec packages/agent-core/spec/os-gate.json).
1 <= items <= 16surface*stringThe codai app on which the override was granted or revoked.
"desktop""headless""codaid""phone""mobile_agent""wear""vscode"app_version*stringVersion of the app that recorded the event.
1 <= length <= 64at*stringWhen the user granted or revoked the override (ISO 8601).
date-timeThe event was accepted into the audit log.
application/json- response
ok*booleancurl -X POST 'https://ai.codai.ro/v1/os-gate/events' \ -H 'Content-Type: application/json' \ -d '{ "action": "granted", "checks": [ "win.uac_off" ], "surface": "desktop", "app_version": "0.9.4", "at": "2026-10-19T21:00:00Z"}'{ "ok": true}