Tokenization for the Claude Agent SDK

How can you protect sensitive data when the Claude Agent SDK talks to a large language model?

Most teams wire the SDK straight into their application code and hand the model raw user inputs, API keys, and internal identifiers, without any tokenization. The request travels over the public internet, the payload is logged by default in client‑side debug output, and the response is stored in memory without any transformation. In that world the only thing standing between a breach and a developer’s laptop is the goodwill of the LLM provider.

This approach creates three concrete problems. First, any accidental log export or debugging session leaks personally identifiable information (PII) or proprietary business data. Second, compliance audits have no evidence that the data was ever inspected, masked, or approved before it left the organization. Third, the application code itself holds the credential that authorizes the Claude service, meaning a compromised host instantly grants unrestricted model access.

Why tokenization matters for LLM agents

Tokenization replaces sensitive fields with reversible placeholders before the data reaches the model. The model sees a token‑ized version of the request, and the service returns a token‑ized response that can be de‑tokenized only by an authorized component inside the trust boundary. This pattern limits exposure, satisfies audit requirements, and enables fine‑grained approval workflows for high‑risk queries.

Even with tokenization, a naïve integration still sends the request directly to Claude’s endpoint. The SDK’s HTTP client talks straight to the cloud service, so the tokenization step is the only guard. If the tokenization library is compromised, or if a developer disables it, there is no additional enforcement point to catch the slip.

The missing controls in a direct integration

The precondition we need to address is simple: we want tokenization, but the request still reaches Claude without any audit trail, without inline masking of returned secrets, and without a just‑in‑time approval step. In other words, the data path is unprotected once the SDK hands off the HTTP call.

Because the SDK runs inside the application process, it cannot enforce policies that require visibility outside that process. Anything that relies on the application’s own logging or environment variables can be tampered with by the same compromised host.

hoop.dev as the tokenization gateway

hoop.dev sits on the network edge as a Layer 7 gateway. When the Claude Agent SDK is configured to route its traffic through hoop.dev, every request passes through a dedicated data path that applies tokenization, inline masking, and session recording before the request reaches the Claude service. hoop.dev is the only component that can enforce those controls because it sits between the SDK and the external endpoint.

On each connection hoop.dev performs three enforcement outcomes:

• Tokenization and de‑tokenization – Sensitive fields are replaced with reversible tokens before leaving the gateway, and the response is de‑tokenized only after the policy check passes.
• Inline masking – If the response contains secrets such as API keys or PII, hoop.dev can redact those values in real time, ensuring they never appear in client logs.
• Session recording and audit – Every request and response is stored as a session record that can be replayed for compliance reviews.

Because hoop.dev is the identity‑aware proxy, it also supports just‑in‑time approval workflows. A high‑risk query can be routed to a reviewer who must approve the request before the gateway forwards it to Claude.

Implementing tokenization with hoop.dev

To adopt this pattern you first deploy the hoop.dev gateway in the same network segment as the application that runs the Claude Agent SDK. The deployment is documented in the getting‑started guide. Once the gateway is running, register a new connection that points to the Claude endpoint. During registration you define a tokenization policy that lists the JSON fields or regex patterns that must be tokenized.

The SDK then points its base URL to the gateway address instead of the public Claude endpoint. From the SDK’s perspective nothing changes – it still uses the same client libraries – but every payload now flows through hoop.dev’s data path.

Because hoop.dev validates OIDC tokens for every request, you can tie each tokenized session to an individual user or service account. This linkage gives you per‑user audit trails without exposing the underlying credential to the application code.

All of the configuration details, including how to write tokenization rules and enable inline masking, are covered in the learn section. The open‑source repository contains example manifests that you can adapt for the Claude Agent SDK.

FAQ

Q: Does hoop.dev store the original data?
A: No. hoop.dev only stores the tokenized representation and the audit metadata. The original plaintext is never persisted outside the short‑lived session.

Q: Can I use hoop.dev with other LLM providers?
A: Yes. The gateway works with any HTTP‑based LLM endpoint as long as you define an appropriate tokenization policy.

Q: How does the approval workflow work?
A: When a request matches a high‑risk rule, hoop.dev pauses the flow and creates an approval ticket. An authorized reviewer can approve or reject the request from the web UI before the gateway forwards it.

By moving tokenization, masking, and audit into the data path, you eliminate the blind spot that exists when the Claude Agent SDK talks directly to the cloud service.

Explore the source code and contribute to the project on GitHub.