Architecture

TapPass sits between your agents and everything they act on — LLM providers, tools, systems of record. Every action passes one decision point: the governance kernel. For the conceptual model, read Concepts first; this page is the system view.

System architecture

Agents connect through surfaces (the gateway, the govern API, MCP, and hooks) using tp_ keys. Every action is run through the governance checks (PII, secrets, injection, session state) and a policy decision, recorded in a tamper-evident audit trail. Provider and tool credentials live in an encrypted vault and are injected upstream, so the real provider keys never reach the agent.

The proxy pattern

Agents talk to TapPass over an OpenAI- or Anthropic-compatible API; TapPass talks to the real provider using keys from its vault:

Your Agent                TapPass                     Provider
    │  Bearer tp_abc123       │                          │
    │ ──────────────────────► │  Governs the request     │
    │                         │  POST  Bearer sk-abc123  │
    │                         │ ───────────────────────► │
    │                         │  ◄────── response ────── │
    │                         │  Governs the response,   │
    │                         │  writes the audit record │
    │ ◄──── response ──────── │                          │

The agent’s key never reaches the provider; the provider’s key never reaches the agent. Both the request and the response are governed, and every decision is recorded.

• Provider keys stay server-side. Agents hold only tp_ keys; the vault injects sk_ keys upstream.
• Governance cannot be bypassed. The decision happens inside the server, not in agent code.
• Per-agent policy. Each agent’s bundle is composed from its own assignment tree.

The kernel

Policy is evaluated in-process on every call — no network hop in the decision path.

• On-demand checks: only the checks a policy actually references run per call.
• Per-agent policy: each agent’s policy is compiled from its assigned versions and content-addressed, so every decision is traceable to an exact policy.
• Fail-closed: a missing policy, an evaluation error, or a failed check blocks the call.
• Deterministic: verdicts are reproducible, which is what makes replay possible.

See How TapPass works for the full decision flow, and the rule reference for what policy can express.

The credential vault

Provider and tool credentials are stored in the vault: encrypted at rest, per-organization isolation, decrypted in memory only at execution time. External backends are supported via KMS envelope encryption (aws_kms://, gcp_kms://, azure_kv://, vault://) and CyberArk Conjur (TAPPASS_SECRETS_BACKEND=conjur).

Capability tokens

For tool execution, the kernel’s allow verdict can be carried to the executor as a capability token (tp_ct_…): a signed, time-bound credential naming exactly what is authorized.

Property	What it gives you
Signed	Offline verification at the executor, no round-trip to the control plane
Non-replayable	A stolen token is useless without the holder’s private key
Attenuation-only	Delegated tokens can only narrow authority, never widen it
Rich constraints	Scope by path, pattern, range, and network
Delegation chains	Cryptographically linked
Trust score	Agent reputation embedded in the token

Executors verify against the JWKS at /.well-known/jwks.json, or call POST /v1/tokens/verify. Tokens are short-lived — the TTL is the revocation window.

from tappass.capability_token import Authorizer, PublicKey

authorizer = Authorizer(trusted_roots=[control_plane_pubkey])
result = authorizer.check(token, "read_file", {"path": "/data/report.txt"}, pop_sig)
if result.authorized:
    ...  # execute

Mandates

For gateway calls, the same idea in lighter form: on allow, the kernel mints a mandate — a compact, short-lived signed token naming capabilities like llm:call:gpt-4o or tool:call:send_email. Downstream services verify mandates offline against the same JWKS. See verdicts & mandates.

Trust scoring

Every agent has a trust score (0–1000) computed from its audit history — no extra instrumentation. It weighs several dimensions of behavior:

Dimension	Measures
Compliance	Pass rate without blocks
Data safety	PII / secret handling
Security	Threat detection rate
Stability	Behavioral consistency
Efficiency	Cost management

The score maps to a clearance level, which constrains what capability tokens can include. Clearance runs from SYSTEM (highest) down through PRIVILEGED, INTERNAL, PARTNER, and EXTERNAL to UNTRUSTED.

Scores and tiers are available at GET /api/trust/scores and GET /api/trust/tiers; a misbehaving agent automatically loses privileged tool access as its score decays.

Next steps

• Security — authentication, encryption, audit integrity
• Concepts — the decision model in detail