Skip to main content

Test Tenants

Overview​

We're making changes to how Test Tenants operate to provide you with better isolated testing resources. Test Tenants will now run in a dedicated environment separate from production, giving you dedicated infrastructure for load testing, integration testing, and development work without any impact on production traffic.

All Test Tenants (tenants with type: "test") will be migrated to this new dedicated environment. This migration ensures better resource isolation and performance for both your testing and production workloads.

Critical Actions Required​

The following changes are required to avoid service interruptions for your Test Tenant traffic. Please review and implement these changes before March 30 2026.

Update API Endpoints​

Action Required: Update all Test Tenant API calls from api.basistheory.com to api.test.basistheory.com

Failure to update your API endpoints will result in service interruptions for Test Tenant traffic after the migration.

See Update API Endpoints for detailed implementation examples.

Update Webhook Signature Verification​

Action Required: Update webhook signature verification to support the new Test Tenant signing key

Test Tenant webhooks will use a new signature version (v1-test) with a different signing key. Your webhook handlers must verify signatures using the appropriate key based on the BT-SIGNATURE-VERSION header.

See Webhook Signatures for detailed implementation examples.

Whitelist New IP Addresses​

Action Required: Add Test Tenant IP addresses to third-party system allowlists

The Test Tenant environment uses different IP addresses for outbound traffic. These must be added to any third-party vendor systems (e.g., payment processors, webhook consumers) that have IP allowlists configured.

Test Tenant IP Addresses:

  • 18.191.73.1
  • 52.13.142.52

See the complete list at IP Addresses.

PCI Compliance Warning​

The Test Tenant environment is NOT PCI compliant. Do not store real or live consumer data in Test Tenants.

Test Tenants should only contain synthetic, non-production data. If you require PCI-compliant testing capabilities, please contact Basis Theory Support to obtain a Production Tenant.

Migration Details​

Impact on Production Tenants: None. Production tenants are completely unaffected by this migration and require no changes. All production traffic will continue to operate normally.

Impact on Test Tenants: Only Test Tenant requests will be affected during the maintenance window.

When: March 30, 2025 at 15:00 UTC

Duration: Approximately 1 hour maintenance window

What will continue to work during the migration (Test Tenants):

  • Read operations (retrieving tokens, listing resources, searching)
  • Invoking proxies and reactors if they're doing read-only operations. If they are creating, updating, or deleting any resources, they will not work.
  • Any Basis Theory Portal operations that read any resources.

What will not work during the migration (Test Tenants):

  • Create operations (creating resources)
  • Update operations (modifying existing resources)
  • Delete operations (removing resources)
  • Any Basis Theory Portal operations that create, update, or delete any resources.
API Response During Migration: Any create, update, or delete operations made through the API during the maintenance window will return a 503 Service Unavailable status code.

Data that will not be migrated:

  • CVCs on card tokens set to expire within 30 days
  • Tokens expiring within 30 days
  • Token intents expiring within 30 days

Required Changes​

Update API Endpoints​

All API calls for Test Tenant traffic must be updated to use the new base URL: api.test.basistheory.com

Using SDKs​

If you're using Basis Theory SDKs, upgrade to the latest version and specify the test environment:

import { BasisTheoryClient } from "@basis-theory/node-sdk";

const client = new BasisTheoryClient({
  apiKey: "YOUR_API_KEY",
  environment: "test"
});
Ensure you're using the latest version of the Basis Theory SDK for your language to access Test Tenant environment support.

Using Direct API Calls​

If you're making direct API calls, update the base URL in your requests:

curl "https://api.test.basistheory.com/tokens" \
  -H "BT-API-KEY: YOUR_API_KEY"

Using Elements​

Elements will follow the same pattern as SDKs. Ensure you're using the latest version and configure Elements to point to the test environment. The specific implementation will follow the SDK pattern - refer to the Elements documentation for your platform.

All existing API keys and authentication will continue to work after the migration. No credential changes are required.

IP Address Allowlisting​

The Test Tenant environment uses dedicated IP addresses for all outbound network traffic. If you have IP allowlists configured in third-party systems, you must add these new IP addresses:

Test Tenant IP Addresses (North America):

  • 18.191.73.1
  • 52.13.142.52

View the complete list of IP addresses for all environments at IP Addresses.

Without proper IP allowlisting, Test Tenant traffic to third-party systems and webhook callbacks will fail.

Webhook Signatures​

Test Tenant webhooks will use a new signature version to allow you to verify webhooks are coming from the correct environment. This requires updating your webhook verification logic to dynamically select the appropriate signing key.

New Signature Version​

Test Tenant webhooks will include BT-SIGNATURE-VERSION: v1-test in the headers, while production webhooks will continue using BT-SIGNATURE-VERSION: v1.

Signing Keys:

  • Production Tenants: https://cdn.basistheory.com/keys/webhooks.v1.key
  • Test Tenants: https://cdn.basistheory.com/keys/webhooks.v1-test.key

Dynamic Verification Implementation​

Update your webhook handlers to dynamically verify signatures based on the BT-SIGNATURE-VERSION header:

Dynamic Webhook Signature Verification
const crypto = require('crypto');
const stringify = require('json-stable-stringify');

// Cache the signing keys
const signingKeys = {
  'v1': null,        // Production key
  'v1-test': null    // Test Tenant key
};

const getSigningKey = async (version) => {
  // Return cached key if available
  if (signingKeys[version]) {
    return signingKeys[version];
  }

  // Fetch and cache the key
  const keyUrls = {
    'v1': 'https://cdn.basistheory.com/keys/webhooks.v1.key',
    'v1-test': 'https://cdn.basistheory.com/keys/webhooks.v1-test.key'
  };

  const response = await fetch(keyUrls[version]);
  const key = await response.text();
  signingKeys[version] = key;

  return key;
};

const verifyWebhook = async (webhookRequest) => {
  const body = JSON.parse(webhookRequest.request.body);
  const signature = webhookRequest.request.headers['BT-SIGNATURE'];
  const signatureVersion = webhookRequest.request.headers['BT-SIGNATURE-VERSION'];

  // Get the appropriate signing key based on version
  const publicKey = await getSigningKey(signatureVersion);

  const verifier = crypto.createVerify('SHA256');
  verifier.update(stringify(body));

  const isVerified = verifier.verify(
    {
      key: publicKey,
      padding: crypto.constants.RSA_PKCS1_PSS_PADDING,
    },
    Buffer.from(signature, 'base64')
  );

  return isVerified;
};
Production webhooks are unchanged and will continue using the v1 signature. Only Test Tenant webhooks will use the new v1-test signature.

Benefits of Dedicated Test Tenant Environment​

Dedicated Testing Resources​

The dedicated Test Tenant environment provides isolated infrastructure for testing workloads, including:

  • Load Testing: Conduct performance and load tests without impacting production systems
  • Integration Testing: Test full integrations in isolation
  • Development: Develop and test new features without production concerns

Transparent Operation​

After completing the required changes above, Test Tenants operate transparently:

  • New Test Tenants are automatically created in the dedicated environment (no environment selection needed)
  • All existing API keys and authentication continue to work
  • No ongoing environment management required

No Production Impact​

Production tenants are completely unaffected:

  • No changes required for production tenant traffic
  • Continue using api.basistheory.com for production tenants
  • No migration or maintenance window for production data

Post-Migration Behavior​

Once the migration is complete and you've updated your endpoints:

  1. All Test Tenant traffic automatically routes to the dedicated environment at api.test.basistheory.com
  2. New Test Tenants are automatically created in the dedicated environment (no additional configuration needed)
  3. Existing authentication continues working without any credential changes
  4. Test Tenant data remains accessible with full functionality restored

Support​

If you have any questions or concerns, please reach out to Basis Theory Support:

If you require PCI-compliant testing capabilities, please contact Basis Theory Support to obtain a Production Tenant for testing purposes.

Last updated on