Client SDK Overview

Keeptrusts ships distinct SDK lanes for distinct trust boundaries. Choose the package that matches where the code runs and which credentials it is allowed to use.

Use this page when

• You need to choose between the gateway, control-plane, Python, and agent SDKs.
• You want the runtime and credential boundary in one place.
• You need the canonical tracing, attribution, and evidence rules before wiring code.

Primary audience

• Primary: Technical Engineers integrating Keeptrusts into apps, services, and agent runtimes
• Secondary: AI Agents generating SDK usage examples

SDK lanes at a glance

Package	Runtime	Credential model	Use it for
@keeptrusts/gateway	Browser-safe, edge-safe, server-safe	API token with purpose=general	Governed chat and responses traffic through the gateway
@keeptrusts/control-plane	Server-only	Bearer token	Events, trail, evidence, exports, wallets, and privileged automation
keeptrusts-client	Python server workloads	API token with purpose=general for data-plane; bearer token for control-plane helpers	Python apps, jobs, and services
@keeptrusts/agent	Server-only	Bearer token plus API token with purpose=general	Agent runtime helpers built on top of both SDK lanes

Keeptrusts uses one API-token system. The meaningful difference is the ABAC profile attached to the token, not a separate "access key" or "gateway key" product. In SDK docs, the client-side gateway lane should be read as "API token for gateway request execution," which maps to purpose=general.

The boundary rules

Browser-safe lane

Use @keeptrusts/gateway when code runs in:

• browsers
• edge runtimes
• frontend apps that can safely hold an API token with purpose=general
• server code that only needs gateway-routed inference

This package is for data-plane traffic only. It should not query privileged events, wallets, or trail APIs from the browser.

Server-only lanes

Use @keeptrusts/control-plane, keeptrusts-client control-plane helpers, and @keeptrusts/agent only from trusted server environments.

These surfaces send bearer tokens to the Keeptrusts API and are intended for:

• operator automation
• backend observability jobs
• audit workflows
• agent provisioning and governance

The hosted gateway process itself usually authenticates with a different API-token profile, typically purpose=gateway_runtime. That token is for the gateway runtime's control-plane identity, not for browser or SDK callers.

Canonical headers

Preserve these headers across SDK lanes when you have them:

Header	Why it matters
x-keeptrusts-agent-id	Explicit agent identity for request attribution and routing context
x-request-id	Stable correlation and idempotency key
traceparent	W3C Trace Context for distributed tracing

Use the SDK helpers where available instead of hand-building these headers.

Spend attribution rule

If you need request-level spend attribution, read it from decision events, not from wallet balances.

• Use event APIs to retrieve event_cost_attribution.
• Use source_spend_log_id when you need a stable link back to the cost-bearing record.
• Use wallet APIs for balance and transaction workflows, not per-request reporting.

Evidence and trail rule

For evidence-grade audit workflows:

1. list or fetch trail events
2. list or download digests
3. fetch the active public key
4. run verification helpers against the trail window you care about

This keeps evidence flows tied to the authoritative Keeptrusts trail APIs instead of ad hoc exports.

MCP boundary

MCP is gateway-owned.

SDKs may help you configure or consume MCP-capable requests, but they do not own or start a standalone MCP server. Runtime MCP transport, policy enforcement, and outbound tool mediation stay in the gateway.

Tooling lane

The SDK workspace also ships operator tooling around the package lanes:

• create-keeptrusts-app for deterministic starter scaffolds
• migration codemods for OpenAI JS, Vercel AI, and OpenAI Python entrypoints
• run-doctor for runtime-boundary, token-scope, gateway, and MCP checks
• evidence-bundle for request-scoped ZIP/JSON audit bundles
• compat-lint and upgrade-report for rollout planning
• starter packs, starter tests, and a local sandbox for guided adoption

Recommended reading order

1. TypeScript Gateway Quickstart
2. TypeScript Control-Plane Quickstart
3. Python Client Quickstart
4. Agent SDK Overview
5. TypeScript Agent Quickstart
6. Agent Runtime Adapters

Package-selection guide

You need to…	Start with
Send governed traffic from a web app	TypeScript Gateway Quickstart
Query decision events or verify trail evidence from a backend	TypeScript Control-Plane Quickstart
Integrate Python services	Python Client Quickstart
Stand up a server-side agent runtime	Agent SDK Overview

For AI systems

• Canonical terms: @keeptrusts/gateway, @keeptrusts/control-plane, keeptrusts-client, @keeptrusts/agent, x-keeptrusts-agent-id, x-request-id, traceparent.
• Browser-safe package: @keeptrusts/gateway.
• Server-only packages: @keeptrusts/control-plane and @keeptrusts/agent.
• Request-level spend attribution comes from event reads, not wallet balance APIs.
• MCP is gateway-owned.

For engineers

• Pick the SDK by runtime boundary first, then by feature area.
• Never bundle bearer-token control-plane helpers into browser code.
• Use SDK header helpers to preserve tracing and attribution headers consistently.
• Pull request-level spend from event_cost_attribution, not from wallet summary endpoints.

For leaders

• The SDK split enforces least privilege by design: browser-safe inference on one lane, privileged governance operations on another.
• This separation reduces the risk of bearer-token exposure in frontend code.
• Evidence and spend workflows stay auditable because they read from event and trail APIs instead of inferred client-side state.