Announcing the Distilled Basis Theory SDK

Tokenize, govern, find, and safely use sensitive data through Effect-native Basis Theory operations.

Sensitive-data infrastructure should make security boundaries more explicit, not hide them behind a mutable singleton and untyped exceptions. @kevinmichaelchen/distilled-basis-theory brings 117 Basis Theory API operations into Effect for token vaults, payment data, proxies, reactors, sessions, and tenant administration.

Basis Theory, at a glance

Basis Theory provides a programmable vault for tokenizing, governing, and safely using payment and other sensitive data. Its API covers the complete token lifecycle alongside access controls, search, token intents, proxies, reactors, 3DS, network tokens, wallets, applications, and tenant resources. Basis Theory maintains an official Node SDK and comprehensive developer documentation.

Why Effect and Distilled?

Vault operations sit directly on a trust boundary. Distilled keeps the Basis Theory application key redacted, injects it only through BT-API-KEY, decodes problem-details responses into typed failures, and exposes explicit retry policies. Effect lets token workflows compose those failures with timeouts, backoff, tracing, concurrency controls, and application-specific recovery without losing the error model.

Configuration is a layer rather than hidden global state. Tests can swap in a test tenant and controlled HTTP client, while production programs can share one reviewed dependency graph. Generated request and response schemas remain committed and inspectable instead of disappearing inside a black-box code-generation release.

How we made the SDK

Code Examples

Set BASIS_THEORY_API_KEY; for a test tenant, also set BASIS_THEORY_API_URL=https://api.test.basistheory.com. Then install:

npm install @kevinmichaelchen/distilled-basis-theory effect

pnpm add @kevinmichaelchen/distilled-basis-theory effect

bun add @kevinmichaelchen/distilled-basis-theory effect

import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
import {
  CredentialsFromEnv,
  tokensCreate,
  tokensGetById,
  tokensSearchV2,
} from "@kevinmichaelchen/distilled-basis-theory";

const BasisTheoryLive = Layer.mergeAll(
  FetchHttpClient.layer,
  CredentialsFromEnv,
);

Tokenize sensitive data

Create a token while keeping searchable business identifiers in non-sensitive metadata. Use only synthetic values in development and follow Basis Theory’s field-specific handling rules for real payment data.

const tokenizeSensitiveData = tokensCreate({
  type: "token",
  data: "synthetic-sensitive-value",
  metadata: { customer_id: "cus_12345" },
  fingerprint_expression: "{{ data }}",
}).pipe(Effect.provide(BasisTheoryLive));

Retrieve a token by ID

Read one known token as part of a controlled workflow. The application key still needs the appropriate token permission for the token’s container.

const retrieveToken = tokensGetById({
  id: "token-id-from-your-database",
}).pipe(Effect.provide(BasisTheoryLive));

Search the vault

Use Basis Theory’s Lucene-based token search to locate records by exact metadata without fetching the entire vault. Search indexes should be designed sparingly because indexed values become discoverable to applications with token:search permission.

const searchVault = tokensSearchV2({
  query: "metadata.customer_id:cus_12345",
  size: 20,
}).pipe(Effect.provide(BasisTheoryLive));

From the same runtime you can create token intents for staged validation, call third-party APIs through proxies, run custom reactors around sensitive data, manage wallet certificates, and inspect audit logs.

Security posture

The SDK redacts credentials, but no client library can make arbitrary application logging safe. Keep sensitive plaintext out of metadata and telemetry, grant the narrowest container permissions, use the test API for development, and follow Basis Theory’s token, search, proxy, and reactor guidance.

Available now

Read the Basis Theory SDK guide, inspect the implementation, browse the spec mirror, or install @kevinmichaelchen/distilled-basis-theory.