@basis-theory/web-agentic

@basis-theory/web-agentic is the browser side of Basis Theory Agentic Payments: the customer-facing steps of the flow run here, and everything that needs a private key stays on your server. The SDK includes AgenticVerification, which runs the provider ceremonies that verify a customer and activate an allowance rail.

This README covers installation and enough of the API to run a first verification. The complete reference — every option, error, and integration pattern — is in the SDK documentation.

Install

npm install @basis-theory/web-agentic

TypeScript declarations are included, and the SDK has no runtime dependencies.

Or load the global bundle. Releases go to immutable versioned paths — pin an exact version (there is no latest) and take its hash from the sibling sri.json:

<script
  src="https://js.basistheory.com/web-agentic/1.2.0/index.js"
  integrity="sha384-…"
  crossorigin="anonymous"
></script>

The bundle publishes the whole SDK on window.BasisTheoryAgentic under the same names npm exports, so every example below carries over by swapping its import for a destructure:

// npm
import { AgenticVerification, ApiError } from '@basis-theory/web-agentic';

// script tag
const { AgenticVerification, ApiError } = window.BasisTheoryAgentic;

AgenticVerification

An allowance rail that requires verification is created in pending_verification, and only a ceremony the provider itself owns can activate it. AgenticVerification runs that ceremony: it advances the verification state machine, renders every customer-facing step, and resolves when the rail is active.

Quickstart

Create a public application in the Basis Theory Portal with only the agentic:allowance:verify permission.

import { AgenticVerification } from '@basis-theory/web-agentic';

const av = AgenticVerification({
  apiKey: 'key_test_us_pub_REPLACE_ME', // PUBLIC application key
  apiBaseUrl: 'https://api.test.basistheory.com/agentic',
  displayName: 'Example Agent',
});

// Read `provider` from the allowance rail — never infer it.
const result = await av.verifyAllowance('alw_...', { provider: 'vic' });
console.log(`Rail is ${result.status} on ${result.provider}`);

If the customer abandons the flow, offer verification again — there is no cleanup step. Nothing the browser sends can activate a rail on its own; Basis Theory confirms every terminal transition with the provider server to server.

Never put a private key in a browser. Public keys are browser-safe by design; the SDK warns loudly if apiKey contains _pvt_.

Browser requirements

• HTTPS top-level origin — ceremonies need a secure context. Locally: cloudflared tunnel --url http://localhost:3000.
• CSP — frame-src must allow the origin of any ceremony iframe the verify response returns; connect-src must allow your apiBaseUrl or custom transport endpoints; with the global bundle, script-src must permit the CDN script. The SDK loads no telemetry or external UI assets.
• Popups — most ceremonies open a window from a user gesture; the built-in interstitials supply it. Content blockers can also stop hosted iframes.

Behavior worth knowing

• verifyAllowance(allowanceId, { provider, rail?, displayName?, timeoutMs?, signal? }) resolves { status: 'active', rail, provider }. rail defaults to 'agentic-token', and aborting the signal rejects with VerificationCancelledError.
• Supported rail/provider pairs: agentic-token/vic (Visa), agentic-token/agentpay (Mastercard) and virtual-card/link (Stripe Link). Name rail: 'virtual-card' explicitly for Link. Anything else throws ConfigurationError before any request is sent.
• Calls are serialized — a second call while one is in flight throws. Verifying an already-active rail resolves without showing a ceremony, as does a rail that needs no cardholder ceremony at all (a delegated Stripe Link allowance, which the consumer approved once when they connected the wallet).
• dispose() aborts any in-flight verification and tears down iframes, popups, listeners and the UI host; for a run in flight that teardown completes as the run settles. It is idempotent and leaves the instance usable, so a remount — React StrictMode, Fast Refresh — can verify again immediately, without awaiting the aborted run.
• Device context is collected automatically on every start and restart; collectDeviceContext is exported for custom transports.

If you pass a complete strings object, note that this release adds linkRedirectTitle and linkRedirectSubtitle. Keys you do not supply fall back to the English defaults, so a localized integration renders English on the Link interstitial until you add them.

The factory also accepts theming, headless, transport, and tuning options — Factory Options documents them all.

Events

onEvent receives these objects. Exceptions thrown by the callback are ignored so observability cannot interrupt verification.

Errors

Errors created by the SDK extend AgenticVerificationError.

import {
  ApiError,
  VerificationCancelledError,
  VerificationNotSupportedError,
} from '@basis-theory/web-agentic';

try {
  await av.verifyAllowance('alw_...', { provider: 'vic' });
} catch (error) {
  if (error instanceof VerificationCancelledError) return; // safe to offer again
  if (error instanceof VerificationNotSupportedError) return; // offer another payment method
  if (error instanceof ApiError) {
    console.error(error.type, error.status, error.traceId); // quote traceId to support
  }
  throw error;
}

ApiError.type is an open set — never switch exhaustively on it. PopupBlockedError is recoverable from a new click, and the SDK retries INVALID_OTP in place and 409 *_IN_PROGRESS with bounded backoff. Every class and per-type behavior: Handle Errors.

Customization

Every surface is replaceable without giving up the SDK's ownership of iframes, popups, protocols, and polling:

• Theming and copy — appearance (six color knobs) and strings restyle the built-in Shadow DOM UI, which is isolated both ways and makes zero external requests. Customize the UI
• Headless — ui: false with handlers brings your own UI; passing a single handler with ui: true overrides just that prompt. The one hard rule: confirmCeremony must call the supplied openPopup synchronously inside the click handler, before any await, or the browser revokes the user gesture. Bring Your Own UI
• Custom transport — verify and getAllowance route API calls through your own backend instead of using a public key; ceremonies still run in the browser. Route API Calls Through Your Backend

Testing

In a test tenant, ceremonies run against Basis Theory-hosted mock pages speaking the exact production protocols, and no request reaches a provider. Tokenize 4242424242424242 (Visa) or 5555555555554444 (Mastercard) for the happy paths; the testing reference lists the test source for every failure scenario.

Browser support

Evergreen Chrome, Edge, Firefox and Safari ≥ 16.4 (the WebAuthn baseline), on desktop and mobile web. Importing the SDK is SSR-safe, but constructing a client accesses the DOM: create the instance after mount or inside a client-only boundary, then dispose it on unmount. For webviews and native shells see Browser Support.

License

Apache-2.0