Regional Endpoints

Basis Theory serves production traffic from multiple regions. Call the API through the endpoint for your tenant's region: https://api.us.basistheory.com or https://api.eu.basistheory.com.

https://api.basistheory.com is the legacy endpoint. It still works, and existing integrations keep running on it, but it is not where a new integration should start. Which one you use decides whether your requests depend on a routing step inside our network: for an EU tenant that step is the difference between a request succeeding and failing during an incident, and for a US tenant it is a dependency you can remove.

The rest of this page explains that difference, how to configure the endpoint in every SDK, and how to migrate an existing integration.

How routing works

Under normal operation, https://api.basistheory.com uses a routing layer inside our edge network to identify your tenant's region and send requests there.

In an edge failure scenario, if we bypass our edge network to restore service, we also bypass that tenant-region routing layer. All traffic sent to https://api.basistheory.com is then routed to the United States.

• EU tenants: This recovery path cannot serve your tenant's data, so requests through the legacy endpoint fail until regional routing is restored.
• US tenants: This recovery path still reaches the region where your tenant's data is served.

Regional endpoints explicitly identify the destination region and do not depend on this tenant-region routing layer. Use https://api.eu.basistheory.com for EU production tenants and https://api.us.basistheory.com for US production tenants.

The endpoints

Endpoint	Hostname	Use it for
United States	https://api.us.basistheory.com	PRODUCTION tenants in the US
European Union	https://api.eu.basistheory.com	PRODUCTION tenants in the EU
Test	https://api.test.basistheory.com	TEST tenants
Legacy	https://api.basistheory.com	Existing integrations only

A regional endpoint is the same API, same keys, same data. A different door into it.

https://api.basistheory.com remains available for backward compatibility. Existing US integrations can continue using it, although we recommend moving to the US endpoint. Existing EU integrations must move to the EU endpoint to preserve access during an edge-network bypass.

For new production integrations, explicitly configure the endpoint for your tenant's region. SDK defaults remain unchanged for backward compatibility; leaving the region unset does not select a regional endpoint. Test tenants must use https://api.test.basistheory.com.

Which endpoint to use

EU tenants — use https://api.eu.basistheory.com. This removes the failure mode above. The legacy endpoint routes you to the EU today, but it leaves every request depending on a step that falls back to a region your data is not served from.

US tenants — use https://api.us.basistheory.com. Nothing breaks if you stay on the legacy endpoint, so this is not urgent. It takes the routing step out of the path entirely, so your requests stop depending on it at all.

Test tenants — use https://api.test.basistheory.com. This one is required rather than recommended. Test tenants run in a dedicated environment in a single region, so there is no regional variant. See Test Tenants.

Test tenants run in their own environment, and https://api.test.basistheory.com is the endpoint for it. https://api.basistheory.com still forwards test-key traffic there, but that is legacy compatibility rather than a supported configuration. Point test traffic at https://api.test.basistheory.com.

Configuring your SDK

Every SDK exposes this as one option. The sections below show each one.

Minimum versions

Regional endpoints need one of these releases or newer:

SDK	Minimum version
Node	6.1.3
Python	7.1.0
Go	7.1.0
Java	8.1.0
.NET	8.1.0
Web Elements	3.1.0 · v2: 2.17.0
React Elements	3.1.0 · v2: 2.17.0
React Native Elements	4.3.0
iOS Elements	5.2.5
Android Elements	2.8.2
Web Agentic	1.3.0
React Agentic	2.1.0
Web 3DS	2.2.1
React Native 3DS	1.2.1, WebView mode

The Terraform provider takes a base URL rather than a named endpoint, so any version works — set api_url to the regional hostname.

React Native 3DS accepts region on BasisTheory3dsProvider, which configures its WebView. Native 3DS — BasisTheoryThreeDSNative and BasisTheoryThreeDSTurbo — has no region option; pass apiBaseUrl to configure() instead.

Precedence

Most SDKs resolve their endpoint by taking the first of these that applies:

1. An explicit base URL — baseUrl, apiBaseUrl, basePath, or api_url — or custom domain routing.
2. A named environment. Test resolves to https://api.test.basistheory.com and takes precedence over a region set alongside it.
3. A named region: US or EU.
4. The default, https://api.basistheory.com.

Your SDK's endpoint changes only when you configure it.

Server-side SDKs

Regions are selected through the environment option.

Node

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

const client = new BasisTheoryClient({
  apiKey: "YOUR_API_KEY",
  environment: BasisTheoryEnvironment.Eu,
});

Python

from basis_theory import BasisTheory, BasisTheoryEnvironment

client = BasisTheory(
    api_key="YOUR_API_KEY",
    environment=BasisTheoryEnvironment.EU,
)

Java

import com.basistheory.BasisTheoryApiClient;
import com.basistheory.core.Environment;

BasisTheoryApiClient client = BasisTheoryApiClient
        .builder()
        .environment(Environment.EU)
        .apiKey("YOUR_API_KEY")
        .build();

Go

import (
  basistheory "github.com/Basis-Theory/go-sdk/v7"
  basistheoryclient "github.com/Basis-Theory/go-sdk/v7/client"
  "github.com/Basis-Theory/go-sdk/v7/option"
)

client := basistheoryclient.NewClient(
  option.WithAPIKey("YOUR_API_KEY"),
  option.WithBaseURL(basistheory.Environments.Eu),
)

.NET

using BasisTheory.Client;

var client = new BasisTheory("YOUR_API_KEY", clientOptions: new ClientOptions
  {
     BaseUrl = BasisTheoryEnvironment.Eu
  });

Terraform

provider "basistheory" {
  api_key = var.basistheory_api_key
  api_url = "https://api.eu.basistheory.com"
}

The Terraform provider takes a base URL rather than a named region. It defaults to https://api.basistheory.com and can also be set with the BASISTHEORY_API_URL environment variable.

Mobile SDKs

iOS

BasisTheoryElements.environment = .EU

Setting environment back to nil, or to .DEFAULT, returns to https://api.basistheory.com. An explicit BasisTheoryElements.basePath continues to take precedence over environment.

Android

val basisTheory = BasisTheoryElements.builder()
    .apiKey("YOUR_API_KEY")
    .environment(Environment.EU)
    .build()

An explicit apiUrl takes precedence over environment, and the resolved URL is used by every client the SDK creates, including proxy requests.

React Native

const { bt } = useBasisTheory("YOUR_API_KEY", { region: "eu" });

React Native shares one API client for the lifetime of the app, so restart the app after changing this rather than expecting a re-render to pick it up.

Web Elements

v3

const bt = BasisTheory("YOUR_API_KEY", { environment: "eu" });

v3 takes a single environment option covering us, eu and test. See initialization and custom domain.

v2

const bt = await basistheory("YOUR_API_KEY", { region: "eu" });

v2 separates the stage from the region: environment names the stage and region names us or eu within it. See initialization.

Selecting an endpoint changes the API host that Elements calls. It does not move the CDN or the iframe origin, which continue to be served from js.basistheory.com, and it does not affect custom domain routing.

Elements resolves the endpoint once, when it initializes. Set the option in your initial call — changing it afterwards does not move an Element that is already mounted.

Agentic SDKs

Web

const verification = AgenticVerification({
  apiKey: "YOUR_PUBLIC_API_KEY",
  region: "eu",
});

React

<BtAiProvider apiKey="YOUR_PUBLIC_API_KEY" region="eu">
  {children}
</BtAiProvider>

3DS SDKs

Web

const bt3ds = BasisTheory3ds("YOUR_API_KEY", { region: "eu" });

React Native

<BasisTheory3dsProvider apiKey="YOUR_API_KEY" region="eu">
  {children}
</BasisTheory3dsProvider>

region configures the WebView this provider renders. If you use native 3DS instead, set the hostname directly:

BasisTheoryThreeDSNative.configure({
  apiKey: "YOUR_API_KEY",
  authenticationEndpoint: "YOUR_AUTHENTICATION_ENDPOINT",
  apiBaseUrl: "https://api.eu.basistheory.com",
});

Migrating from the legacy endpoint

For integrations already calling https://api.basistheory.com. Nothing moves but configuration — no data, no keys, no request changes.

Before you start. Confirm which region your tenant is in — contact support if you are not sure. You cannot rehearse this with a TEST tenant, so confirming US or EU takes a production tenant in that region and its own key.

1. If you use an SDK, upgrade to a version that supports regional endpoints. Older versions may expose US and EU options that still resolve to https://api.basistheory.com.
2. Configure one client for your tenant's region — see Configuring your SDK. Check for an explicit base URL or custom domain that takes precedence over the region setting.
3. Confirm that outgoing API requests target api.eu.basistheory.com for an EU tenant or api.us.basistheory.com for a US tenant. If you use a custom domain, confirm its regional routing with support.
4. Run an operation your integration already performs and confirm it succeeds. If it fails, verify that the endpoint matches the tenant associated with your API key, and that the key has permission to perform the operation.
5. Apply the configuration to your remaining clients and verify their request hostnames.

If you need to revert, removing the option puts that client back on the legacy endpoint, which still serves US and EU tenants. Test traffic belongs on https://api.test.basistheory.com either way.

Do not point an EU tenant at the United States endpoint, or a United States tenant at the EU endpoint, as a failover strategy. A request for data that does not live in the region you named will not be served by it.