---
name: bt-production
description: Prepare Basis Theory integrations for production readiness.
license: MIT
metadata:
  tier: core
  last_verified: '2026-09-25'
---

# Production readiness

## The checklist is canonical — parity is the judgment

Fact: Basis Theory publishes a production checklist — https://developers.basistheory.com/docs/guides/production-checklist. Use it as the baseline. This skill adds practical guidance around it: most go-live incidents are _environment parity_ failures, not missing features.

## The parity sweep (run before cutover, and again after any tenant/environment change)

Test and production tenants differ by design (https://developers.basistheory.com/docs/api/test-tenants). Verify each of these explicitly — assume drift until disproven:

1. **Endpoints**: no `api.test.basistheory.com` (or PSP sandbox URLs) reachable from production code paths. Grep for hardcoded URLs — including inside proxy destinations and transform configs, the classic hiding place.
2. **Key→environment mapping**: every credential in production config provably belongs to the production tenant; no test keys smuggled in via defaults, CI variables, or "temporary" overrides. Key management and rotation: https://developers.basistheory.com/docs/api/applications/application-keys (scoping guidance in `bt-architecture`).
3. **IP allowlists**: production outbound IPs differ from test — https://developers.basistheory.com/docs/api/ip-addresses. Update firewalls and _downstream_ allowlists (PSP-side too).
4. **Webhook signatures**: production signs differently than test (`v1` vs `v1-test`); verification code must select by environment, and webhook endpoints must be re-registered for the production tenant.
5. **Feature enablement**: anything that required Basis Theory-side setup in test (3DS, network tokens, account updater, Apple Pay) needs its production enablement confirmed — sandbox enablement does not carry over. Plan lead time.

## Operational hardening

- **Key hygiene**: unique application per workload, least-privilege scopes, a rehearsed rotation plan (rotation you've never rehearsed is an outage waiting for a compromise), no shared human/service credentials.
- **Account security**: enforce MFA and restrict login providers/domains for the tenant — https://developers.basistheory.com/docs/features/identity; enterprise SSO: https://developers.basistheory.com/docs/features/sso/ (OIDC: https://developers.basistheory.com/docs/features/sso/configure-sso-with-oidc, Okta: https://developers.basistheory.com/docs/features/sso/configure-sso-with-okta, SAML: https://developers.basistheory.com/docs/features/sso/configure-sso-with-saml). Note the documented warning: enforcing MFA or provider restrictions removes non-conforming users from the tenant — sequence comms before flipping enforcement.
- **Permission hygiene the checklist now asks about** (Fact, verified 2026-09-25): no `token:update` on Public Applications unless strictly necessary, and Management keys with `application:create` / `application:update` treated as administrative credentials — few holders, provisioning automation only, rotate on exposure (https://developers.basistheory.com/docs/guides/production-checklist). The PCI item is now "complete the SAQ your acquirer or processor requires", not SAQ-A specifically.
- **HTTP client configuration**: one client and connection pool per process, idle timeout at or under 30 seconds, connection lifetime at or under 5 minutes, explicit connect/request timeouts with idempotency keys. Stale pooled connections surface as `UNEXPECTED_EOF_WHILE_READING` before any response and are not truncated responses (https://developers.basistheory.com/docs/api/client-configuration).
- **Monitoring**: subscribe to status (https://developers.basistheory.com/docs/api/status); alert on error-rate and latency at the Basis Theory call sites; log correlation IDs at every boundary so incident evidence exists before the incident (`bt-test-debug`). For Reactors and Proxy code transforms on Node.js images, decide whether to enable runtime logs and who consumes the `reactor.log` / `proxy.log` webhooks (`bt-reactors`).
- **Deprecations**: track https://developers.basistheory.com/docs/api/deprecations on a calendar, not on memory. Current example: `node-bt` cannot be selected for new Reactors or Proxy code transforms from the listed date; existing resources keep running, so plan the migration to `node22` / `node24` (https://developers.basistheory.com/docs/concepts/runtimes/migrate-from-node-bt).

## Existing-code mode

1. Run the parity sweep against the actual repo and config — produce a findings table (item / status / evidence), not a generic checklist echo.
2. Fix what code can fix (environment-aware config, signature-version selection, URL de-hardcoding); list what only the customer can do (production tenant creation, key custody, firewall changes, PSP production credentials) as the customer-owned remainder.
3. Verification: a smoke test that runs the critical path against production config _with test-mode assertions off_ — reads and health checks only; never generate live charges as a "test."
4. Final report: green/amber/red per checklist item, with the honest amber list — a go-live report that says "all green" without evidence is the anti-pattern this skill exists to prevent.

Escalate to Basis Theory (with evidence) when: production enablement status is unknowable from outside, limits/quotas need adjustment for launch traffic, or compliance attestations are requested — those are Basis Theory conversations, not docs lookups.

## Basis Theory implementation guidance

When the answer needs implementation judgment beyond public docs, load only the relevant slices below from [../\_shared/references/implementation-guidance/README.md](../_shared/references/implementation-guidance/README.md). Treat these as implementation patterns, not canonical product behavior; keep public docs as the source of truth and label the guidance as **Implementation pattern** or **Assumption** unless docs prove it.

- `../_shared/references/implementation-guidance/environment-parity-checklist.md`

<!-- bt-conventions:start -->

## Working conventions (shared by all Basis Theory skills)

- Public Basis Theory docs are the source of truth for product behavior. Link the specific docs page behind any product claim; if a skill and the docs disagree, follow the docs.
- Keep customer ownership clear: customers own PSP accounts, credentials, compliance decisions, production rollout, and application code. Skills can guide plans, bounded changes, and examples; they do not certify production readiness.
- Never request, echo, store, or commit real credentials. Use placeholders such as `<BT_API_KEY>` and prefer sandbox or synthetic data for examples.
- If a live-looking credential, live cardholder data, or production secret appears, stop mutation work, tell the user exactly where it appeared, and require rotation/revocation before continuing.
- Default to test tenants and PSP sandboxes. Do not run or recommend production charges, refunds, card reveals, credential migrations, or data moves unless the user explicitly asks and the plan names safeguards, rollback, and customer approval.
- Treat vague planning, audit, review, and “should we” prompts as read-only unless the user explicitly asks for a bounded implementation change.
- Before changing product code, map the existing checkout/data flow, credential-bearing paths, persistence, retries, refunds, webhooks, logs, and rollback expectations.
- End with an honest final report: done, assumed, remaining, proof run, unverified live behavior, rollback, and go-live items.
<!-- bt-conventions:end -->