Gatekyper core concepts

The model in one line

A provider credential stays encrypted behind Gatekyper. A named actor receives a Gate Token attached to explicit policy. The gateway evaluates that policy and records the result for every request.

access model

provider credential
  → provider integration and active route
  → gateway policy decision
  → scoped Gate Token for one actor
  → usage event or denial event

Ownership and identity

Organization: The top-level ownership boundary for users, projects, provider integrations, policies, tokens, and audit events.
Project: A workload or business boundary used to group apps, actors, tokens, budgets, and usage.
Application: A software workload within a project, such as an API service, worker, CLI, scheduled job, or local tool.
Actor: The human, app, service, or AI agent responsible for a request. Agent MCP sessions map to known actor identities.
Environment: The dev, test, staging, or production context carried by a token. Production access requires explicit policy.

Providers and credentials

Provider integration

A provider integration describes the provider type, display name, base URL, status, and supported adapter. Gatekyper routes only through implemented adapters and allowlisted paths.

Provider credential

A credential is one encrypted secret version attached to a provider integration. Its lifecycle is candidate, active, retiring, revoked, or failed. Read APIs return a redacted hint, never the reusable plaintext.

Rotation

Add and test a candidate, activate it, let the previous credential retire, then revoke the old version. Gate Tokens point to policy and provider routes rather than embedding the provider secret, so callers do not need new tokens for the rotation.

Gate Tokens

A Gate Token is an internal credential accepted only by the Gatekyper gateway.

synthetic formats

gk_live_<public_id>_<secret>   # production identity
gk_test_<public_id>_<secret>   # development or test identity
gk_tmp_<public_id>_<secret>    # temporary identity

Public identifier: Stored in plaintext for indexed lookup. It is never enough to authenticate.
Secret: High-entropy random material shown once at issuance and never retrievable later.
Stored verifier: A HMAC-SHA256 of the secret using a server-side pepper, compared in constant time.
Ownership: Optional project, application, and actor links identify the token’s operational purpose.
Lifecycle: Active, expired, disabled, or revoked, with optional explicit expiration.

Policies and capabilities

A token must have a valid attached policy. The policy engine compares normalized request context to an explicit allowlist and denies by default.

Provider: Limits which implemented adapter can receive the request.
Capability: A normalized action such as ai.chat, ai.embeddings, ai.image.generate, code.repo.read, or code.repo.write.
Model and endpoint: Optional allowlists refine the provider capability to known models or native paths.
Environment: Production must be explicitly allowed; a dev token does not inherit production authority.
Required metadata: A policy can require task, trace, app, or agent context through Gatekyper request headers.
Rate and expiry: Request windows and token expiration bound velocity and time.

Budgets: reserve, then settle

A stale “check current spend” is not enough when several requests start together. Gatekyper uses a two-phase budget model for enforceable hard-stop windows.

Estimate a conservative maximum cost for the proposed request.
Atomically reserve that amount against each applicable budget window.
Deny before the provider call if a hard-stop reservation cannot be made.
After the response or stream ends, settle the reservation to observed estimated cost.
Expire abandoned reservations by TTL so crashed requests do not hold budget forever.

Usage, denials, and audit

Usage event: Written for a request that reached a provider, including success, provider error, gateway error, or cancellation.
Denial event: Written for a request blocked before the provider call, with a safe reason and request identifier.
Audit event: Records sensitive management actions such as credential activation, token issuance or revoke, policy changes, approvals, and kill switches.
MCP invocation: Records each agent tool call with redacted arguments, result status, and any resulting access request.

Usage and denial events are intentionally separate and do not overlap. A dashboard may present them together, but they answer different questions.

Agent access requests

An access request is a structured proposal for new temporary authority. It contains the actor, project, purpose, provider, capabilities, models, budget, expiration, estimated calls, and task context.

An authenticated MCP actor submits a token request.
A bounded low-risk template may auto-approve it; otherwise it remains pending for a human.
An administrator approves, edits, or denies the request in the dashboard.
The requesting actor polls request status and receives approved token plaintext exactly once.
Later polls return status and token metadata without replaying the secret.

Revocation and kill switches

Normal revocation stops one Gate Token. Kill switches provide broader containment by token, actor, project, provider, environment, agent-created token class, or the entire gateway. The emergency switch blocks provider proxying while preserving management access.