Skip to Content
Concepts

Concepts

Keel evaluates supported actions against customer-defined authorization rules before dispatch and records decisions and associated evidence.

Connect an application

Use Quickstart to create a project, configure credentials and rules, send a supported request, and inspect its decision. Keel does not intercept requests your application sends directly to other systems.

The APIs have different request formats and supported operations. The decision-only API does not execute an action; its caller must enforce the decision. For those responsibilities and the dispatch details, see How Keel Executes Authorized Actions. Jobs return status, usage metrics, provider/model metadata and available asset references.

Generated text bodies are not returned by jobs. Use a supported sync or stream route for text.

Core domain objects

Every other page on this site references the objects below.

Project

The unit of tenancy. Projects hold policy overrides, permits, governed request state, provider keys, runtime API keys, async jobs, and observability data. All Keel public runtime routes scope to a project.

Project API key

The runtime credential a caller sends to public permit, execute, executions, proxy, jobs, and request-timeline routes. Project API keys are project-scoped and authenticate every request. They are stored hashed; raw key material is shown once at creation and is never returned again.

Provider key

A server-side provider secret stored per project. Keel execution dispatches use the project’s stored provider key. Provider keys are encrypted at rest with AES-256-GCM and are never returned to runtime callers in raw form.

AI Permit

An AI Permit is a pre-execution decision record. It may allow, deny, throttle or require review.

An AI Permit is not the same as approval. Only an allow decision authorizes execution. Deny, throttle and review-required outcomes are also AI Permits. Exception: on managed MCP tool calls (POST /v1/mcp/servers/{server}/tools/{tool}:call), a policy throttle answers 429 with nothing dispatched and is recorded as a governance decision record, not as an AI Permit, so it does not appear in Permit-based exports. The internal protocol calls the review-required state challenge; public API response models serialize it as review.

Where supported, Keel cryptographically signs and binds the AI Permit and its decision evidence.

The permit record captures the decision, reason code, matched policy, budget snapshot at decision time, routing intent, and request fingerprint. It is the canonical anchor for usage, verification, replay and signed exports.

Current signing behavior has one important boundary: allow Permits must have a valid signed binding before dispatch. If runtime signing is unavailable, non-allow outcomes can still be persisted without a binding signature so the decision record is not lost.

When a server-owned semantic contract passes Keel’s admission gates, the same primitive can use a more specific customer title: AI Permit-to-Work for one bounded job, AI Permit-to-Pay for exact payment authorization, or AI Permit-to-Generate Text for exact server-built text-generation authorization. The title describes the record; it never replaces the decision or signed scope. See AI Permit-to-X.

Decision

A decision is the outcome Keel records after evaluating an intended action against applicable identity, policy, scope, arguments, budget, routing, delegation, approval and other decision facts. The decision is part of the AI Permit.

Decision evidence

Decision evidence records the Permit decision, the facts bound into it and the applicable integrity and provenance material. Every AI Permit records decision evidence. Independent verification depends on which signed artifact and plan entitlement are available.

Execution evidence

Execution evidence is lifecycle evidence produced when Keel manages execution or when a supported closeout flow adds evidence. It may record dispatch, provider response, usage, cost, delivery or closure facts. It does not by itself prove that the ultimate external side effect occurred exactly as intended.

Receipt

A receipt is supporting evidence produced by Keel, supplied by a customer or originating from a provider or external authority. Its strength depends on provenance, bindings, signature or validation method and verification state. A receipt is not an AI Permit.

Verification

Verification checks supported signatures, hashes, bindings, lineage, trust material and internal consistency. It does not establish completeness, policy correctness, legal or regulatory compliance, objective external truth, that every relevant event was captured, or that the ultimate side effect occurred.

Governed request

The logical request-level record Keel uses to track final decision, final status, billability, and the surface that produced it. A governed request typically corresponds to a permit and an execution event sequence; the governed request is the layer that ties them.

Async job

A persisted background execution record with its own status, request id, result assets, usage metrics, and callback metadata. Async jobs reuse the same governance and execution pipeline as sync routes; the status semantics differ.

Execution event

A normalized lifecycle event such as routing.selected_model, provider.request_sent, usage.recorded, job.processing, or request.completed. Execution events feed Timeline Replay and are the building blocks of customer-visible request lifecycles.

Request timeline

A replay view reconstructed from persisted permits, governed request rows, execution events, async job rows, and usage rows. The timeline is rebuilt from persisted data only; Keel does not interpolate latency, durations, or state transitions that were not written.

Routing

The explicit selection of a provider/model target for a governed request — including alias resolution on POST /v1/execute, request-scoped routing on POST /v1/executions, and explicit fallback chains. See Routing for the two-layer model and per-surface capability matrix.

Usage record

The actual execution accounting attached after dispatch — token counts, cost in microdollars, provider response identifiers, and timing. Provider execution surfaces record route-appropriate usage; on advanced external-enforcement integrations, usage is reported back through POST /v1/permits/{permit_id}/usage.

What this surface does and does not claim

  • Execution is the normal product path. The execution request shapes are not interchangeable, but Keel owns dispatch on each.
  • Advanced external enforcement is available by request. Keel owns the decision but the trusted external system owns provider transport. Keel does not directly observe the provider call; reported usage and attached verification material remain supplied evidence, not direct observation of the external action.
  • Realtime session authority is presented as AI Permit — Realtime session, not Permit-to-Speak or Permit-to-Talk. Session authorization does not establish participant identity, recording consent, or authority to represent someone.
  • The objects in the glossary are persisted records, not synthetic abstractions. Every object listed has a database backing, an audit trail, and stable identifiers.
Last updated on Edit this page on GitHub 
ArchitectureQuickstart