How Keel Executes Authorized Actions

Keel evaluates supported actions against customer-defined authorization rules before dispatch and records decisions and associated evidence. Managed execution describes how Keel operates; it is not a separate product, opt-in mode, or special tier. This is the authoritative advanced explanation of that architecture. Start with Quickstart to connect an application.

The dashboard configures projects, credentials, rules, and controls and displays recorded activity. Opening the dashboard or creating an account does not place external actions under Keel’s control. Applications must use a supported integration.

Authorization and dispatch

For a supported request that Keel executes, it authenticates the caller, evaluates the request and applicable controls, records the authorization decision, and checks that the permit is executable before dispatch. Denied, throttled, or unresolved review outcomes do not authorize dispatch. An allow decision alone does not override outstanding approval requirements, expiry, or the request’s supported constraints. See Decision Model for exact outcome and approval semantics.

Customer-defined rules evaluate the request and context supplied through the documented integration. They do not give Keel independent knowledge of mission state or external operating conditions. Standalone decision, preparation, and dry-run APIs do not dispatch an action; dry-run does not issue or persist an AI Permit.

What the evidence records

Keel records the decision and lifecycle information available for the supported operation: dispatch attempts, provider responses, usage, cost, and closure information where supported. A recorded provider response establishes what Keel received, not that the provider’s reported outcome is independently true. Missing or estimated usage must not be presented as exact observed usage.

When an external system executes the action, its supplied reports, receipts, or callbacks remain distinct from Keel’s own observations. Generic receipt and callback closeout does not by itself establish provider origin or independently verify the external effect. Supported signature and binding checks establish the properties of those artifacts, not execution success, mission outcome, or completeness of all events.

See Request Lifecycle, Reconciliation, and Verifying Evidence for event, accounting, and artifact details.

Supported integrations and limits

The APIs below use different request formats and sync/async behavior within Keel’s standard model. Support is operation- and provider-specific; use Provider Support, Capability Matrix, and Scope and Limits before integrating. This page does not claim arbitrary tool or runtime support, interception of calls that bypass Keel, offline enforcement, or guaranteed downstream success.

Advanced integrations using another trusted system for enforcement and dispatch are available by request. They use decision primitives; they are not a feature customers must activate to obtain Keel’s normal authorization behavior. The external system’s responsibilities are described below.

For the orienting glossary that introduces these surfaces, see Concepts.

At a glance

Realtime session routes provide decisions and observations; they do not proxy arbitrary media or dispatch customer-owned tools. Advanced external enforcement is available by request through decision primitives such as POST /v1/permits; the trusted external boundary owns enforcement, provider transport, and credentials.

Reading the table:

• Provider call by — who issues the HTTP request to the upstream provider. Keel for the execution surfaces above; an external system in an advanced integration.
• Provider key held by — where the upstream provider’s API key lives. Keel execution surfaces resolve provider credentials server-side; advanced external enforcement leaves credentials with the external system.
• Request shape — the body the caller must construct.
• Response shape — what the route returns. Normalized envelopes are stable across providers; proxy response shapes depend on the route. The original Anthropic nonstreaming route returns an OpenAI-shaped envelope, while its SDK Messages path returns a native Anthropic Message.

Unified execute

Route: POST /v1/execute.

Who it is for. Applications that already have a provider-shaped input payload and want Keel to handle target resolution, permit evaluation, dispatch, and a normalized response. Unified execute is the primary public runtime surface for new integrations.

What Keel owns

• Target resolution before execution (alias resolution, project-scoped health, active routing budgets)
• Permit evaluation
• Provider dispatch through adapters
• Normalized response envelope plus a resolved metadata block
• Usage and accounting persistence

What the caller owns

• Constructing the provider-shaped input payload
• Choosing whether to send provider/model explicitly or let Keel resolve

Trade-offs. Less provider-native than the proxy routes; not interchangeable with POST /v1/executions despite the similar name.

Current limits

• Target resolution is explicit and rule-based, not a claim of broad autonomous routing.
• The surface is beta (see Surface Maturity) and is not the same request shape as /v1/executions — see Routing for the per-surface capability matrix.

Provider-neutral execution

Route: POST /v1/executions.

Who it is for. Applications that want a single canonical request and response shape across providers. The execution contract is provider-neutral: the same operation and inputs produce stable, normalized outputs regardless of which provider Keel dispatches to.

What Keel owns

• Permit formation and evaluation
• Routing plan binding from the public routing envelope
• Provider dispatch through adapters
• Usage reconciliation, ledger writes, and lifecycle persistence

What the caller owns

• Canonical input construction (operation, messages or inputs, parameters, optional routing)
• Any client-side retry policy against the Keel API
• Choosing sync or the current stream subset

Trade-offs. Cleaner than provider-native proxies for multi-provider integrations; narrower than provider-native surfaces — not every provider-specific feature is exposed through this contract. The provider-neutral envelope is the most portable shape Keel offers.

Current limits

• Streaming is narrower than the non-stream path.
• Routing and fallback behavior are bounded by the surface’s routing capability matrix.

Provider-specific proxy

Routes: POST /v1/proxy/openai, POST /v1/proxy/anthropic, POST /v1/proxy/google, POST /v1/proxy/xai, POST /v1/proxy/meta.

Who it is for. Applications that need a provider-specific payload and a documented proxy response shape while Keel governs the request, holds provider credentials, and persists audit evidence. The proxy surface is the appropriate choice when the caller depends on a provider-specific feature that the provider-neutral contract does not expose.

What Keel owns

• Stripping known transport and auth override fields from the inbound payload
• Permit evaluation and supported prompt-firewall checks
• Provider-key lookup and adapter dispatch
• Idempotency replay and caching on proxy paths
• Usage and accounting persistence and response headers

What the caller owns

• Constructing provider-native payloads
• Understanding provider-specific differences in supported operations and streaming behavior

Trade-offs. Closest to provider semantics; highest route-specific behavior — proxy routes are not interchangeable with one another. Response shape and capability coverage differ by route.

Current limits

• Public routing is exposed only on the OpenAI and Anthropic proxy routes.
• Public streaming is currently primarily implemented on the OpenAI proxy.
• Capability coverage differs by provider — see Proxy Execution.

Async jobs

Routes: POST /v1/jobs, GET /v1/jobs/{job_id}.

Who it is for. Applications that want authorized execution decoupled from the request/response lifetime — for example, batch processing, long-running generation, or workloads where the caller does not want to hold an HTTP connection open.

What Keel owns

• Job persistence and queue state
• Background execution through the shared governance and execution pipeline
• Usage and accounting persistence
• Optional best-effort callback delivery

What the caller owns

• Submitting the canonical permit plus provider payload
• Polling job status or receiving best-effort status callbacks
• Handling eventual completion instead of inline results

Trade-offs. Durable status plus optional callback support; more moving parts than sync routes; distinct job_id and request_id lifecycles.

Current limits

• Callback URLs must pass outbound-policy validation.
• Async uses shared governance and execution machinery, but status semantics are job-oriented rather than identical to sync routes.
• GET /v1/jobs/{job_id} returns status, usage metrics, provider/model metadata and result_assets where present. Callbacks contain status, usage metrics and available asset references. Generated text bodies are not returned by jobs; use a supported sync or stream route when you need generated text.
• Async job callbacks use bounded in-process retries; callers that need durable outbound delivery should use webhook subscriptions instead. A webhook callback host must first be allowlisted by Keel (exact hostname); until then POST /v1/webhooks is refused.
• Background completion and a stored provider response do not establish delivery to the client. An async worker can record provider receipt with client_digest_missing closure evidence; only an observed HTTP response delivery supplies a client-response digest and delivery time. A later job-status poll is a separate HTTP response, not proof that the original worker result reached the client.
• Closure evidence for async jobs is not supported. A signed full_audit export authenticates a job’s Permit and its chain events, but the job’s closure record carries no completion time or client-response digest, so the export declares no closure claim for it and keel-verify --verify-closure cannot verify an async job’s closure.

Realtime session governance

Routes: POST /v1/sessions, session-scoped event and turn routes, and POST /v1/sessions/{session_id}/end.

Who it is for. Customer-operated voice gateways and sidecars that need a session permit, locked policy snapshot, turn decisions, action-child permits, and verifier-readable session evidence while retaining their provider media connection.

What Keel owns

• Session-start and turn policy decisions
• Action-child permit issuance for external tool calls
• Validation and persistence of submitted signed voice atoms
• Session-chain and attestation assembly from the evidence Keel received

What the caller owns

• The provider connection, audio capture, playback, and provider credentials
• Enforcing each Keel decision before an external tool call
• Provider-specific retry, interruption, and reconnection behavior
• The truth and completeness of sidecar-submitted events and terminal usage

Trade-offs. This applies Keel’s session governance and evidence model without moving raw voice media into Keel. It is not the same dispatch boundary as /v1/execute, /v1/executions, or /v1/proxy/*: arbitrary media and tool actions performed by the customer runtime remain outside Keel dispatch. The realtime conversation itself is not Keel-governed: session evidence records what the gateway submits and does not control audio or text streaming.

See Realtime Voice for the OpenAI GPT-Live and Realtime adapter boundary and the session endpoint sequence.

Advanced external enforcement — by request

Route: POST /v1/permits (decision); POST /v1/permits/{permit_id}/usage (closeout).

Who it is for. Architectures that already have another trusted enforcement point and require an advanced integration by request. Keel records the policy and budget decision in an AI Permit; the external system owns downstream enforcement, the provider call and the truthfulness of later closeout material.

What Keel owns

• Request authentication and project scoping
• Canonical permit evaluation (policy, budget, governance event)
• Idempotent permit persistence
• Optional later usage closeout through the public usage route

What the caller owns

• The actual provider call and its credentials
• Retry and transport behavior
• Collecting final usage and cost
• Reporting completed usage back to Keel when desired

Trade-offs. Narrow integration contract and decoupling from provider transport, but no Keel-controlled dispatch boundary and less automatic lifecycle evidence. Use it only when the external enforcement point is trusted to honor the decision and constraints.

Current limits

• Public Permit closeout requires supplied receipt or callback material and a positive billed cost. That material adds closeout evidence; it does not make the caller-owned provider call directly observed by Keel.
• The prompt firewall does not run on permit-only requests.
• Caller-executed traffic is outside Keel’s outbound policy because Keel does not make the provider call.
• Reported usage and attached verification material are supplied evidence; attaching them does not make the external execution directly observed by Keel. For the broader observation boundary, see Scope and Limits § Advanced external-enforcement observation boundary.

Worked example: execution surfaces and an advanced integration

The same task (“summarize a customer support ticket in one sentence”) implemented three ways. The differences are not in the AI work — they are in who owns dispatch and what the caller’s code looks like.

Hosted Keel requires a current X-Keel-Timestamp (Unix seconds) and a new X-Keel-Nonce (at least 16 characters) on each request to /v1/execute, /v1/proxy/* and POST /v1/permits; requests without them return 401 request_not_fresh. Generate both again for every retry. See Request Freshness.

As unified execute

curl -sS -X POST https://api.keelapi.com/v1/execute \
  -H "Authorization: Bearer keel_sk_<project_key>" \
  -H "Content-Type: application/json" \
  -H "X-Keel-Timestamp: $(date +%s)" \
  -H "X-Keel-Nonce: $(openssl rand -hex 16)" \
  -H "Idempotency-Key: ticket-1234-summary" \
  -d '{
    "provider": "openai",
    "model": "gpt-4o-mini",
    "input": {
      "messages": [
        {"role": "user", "content": "Summarize this ticket in one sentence: <ticket-body>"}
      ],
      "max_tokens": 80,
      "temperature": 0
    }
  }'

Keel resolves the target, evaluates the permit, calls OpenAI, and returns a normalized envelope with both the model output and a resolved block describing the selection.

As provider-specific proxy

curl -sS -X POST https://api.keelapi.com/v1/proxy/openai \
  -H "Authorization: Bearer keel_sk_<project_key>" \
  -H "Content-Type: application/json" \
  -H "X-Keel-Timestamp: $(date +%s)" \
  -H "X-Keel-Nonce: $(openssl rand -hex 16)" \
  -H "Idempotency-Key: ticket-1234-summary" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Summarize this ticket in one sentence: <ticket-body>"}
    ],
    "max_tokens": 80
  }'

The body is the OpenAI-native chat-completion payload. Keel evaluates the permit, dispatches to OpenAI, and returns OpenAI’s native response shape with Keel headers attached for governance correlation.

Advanced: external enforcement by request

# 1. Ask Keel for a decision.
curl -sS -X POST https://api.keelapi.com/v1/permits \
  -H "Authorization: Bearer keel_sk_<project_key>" \
  -H "Content-Type: application/json" \
  -H "X-Keel-Timestamp: $(date +%s)" \
  -H "X-Keel-Nonce: $(openssl rand -hex 16)" \
  -d '{
    "project_id": "<project_uuid>",
    "idempotency_key": "ticket-1234-summary",
    "subject": {"type": "user", "id": "agent_42", "attributes": {}},
    "action": {"name": "ai.generate", "attributes": {}},
    "resource": {
      "type": "request",
      "id": "ticket_1234",
      "attributes": {
        "provider": "openai",
        "model": "gpt-4o-mini",
        "estimated_input_tokens": 800,
        "estimated_output_tokens": 60
      }
    }
  }'
 
# 2. If the decision is "allow", call OpenAI from your application.
# 3. Report observed usage back to Keel. Closing out an externally enforced request
#    requires an admin-scope project API key and verification material.
curl -sS -X POST https://api.keelapi.com/v1/permits/<permit_id>/usage \
  -H "Authorization: Bearer keel_sk_<admin_project_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "actual_input_tokens": 812,
    "actual_output_tokens": 47,
    "actual_total_tokens": 859,
    "cost_usd_micros": 215,
    "usage_idempotency_key": "ticket-1234-usage",
    "verification": {
      "method": "provider_receipt",
      "provider_request_id": "req_ticket_1234",
      "receipt_json": { "request_id": "req_ticket_1234" }
    }
  }'

What changed

• Unified execute lets the caller stop maintaining a direct OpenAI dependency and gives back a normalized response that does not change shape if Keel later routes to a different provider.
• Provider-specific proxy keeps the caller on OpenAI’s native API surface, which is the right choice when the caller depends on an OpenAI-specific feature that the canonical envelope does not expose.
• External enforcement preserves a caller-owned OpenAI path, but that trusted external system must enforce Keel’s decision and constraints.

How to choose

For new integrations, unified execute is the recommended default. It has the lowest friction with route-appropriate Keel evidence. Provider-specific proxy is the compatibility path when a provider-specific feature is essential. Advanced external enforcement is available by request and requires a trusted system outside Keel to enforce the decision before downstream execution or dispatch.

What this surface does and does not claim

• The execution routes are not interchangeable. Choose by request shape and whether you need sync results; Keel owns dispatch on each.
• Keel does not directly observe an externally executed provider call. The verification track attaches supplied receipt or callback evidence; it does not independently establish the downstream outcome.
• Public realtime governance is exposed through /v1/sessions and its session-scoped evidence routes. These routes do not proxy the provider media stream and do not turn customer-executed tools into Keel dispatch.
• Supported execution routes share the same standard execution model. Individual capabilities remain plan-gated: see Plans & Entitlements for cross-provider routing, prompt-firewall strengthening, integrity verification API, and other gated features.

Related pages

• Concepts — orienting glossary
• Quickstart — send a first governed request
• Permits — the permit record contract
• Executions — provider-neutral execution surface
• Execute — unified execute surface
• Proxy Execution — provider-native proxy surfaces
• Routing — per-surface routing capability matrix
• Plans & Entitlements — capabilities gated within supported surfaces