Pre-Configured Proxies

Pre-Configured Proxies differ from the Ephemeral Proxy by requiring setup beforehand. You define a proxy instance with a unique URL and fixed settings, which can be reused across requests or shared with third parties for inbound HTTP requests (e.g., providing an integrator with a proxy URL). This approach suits scenarios needing consistent configurations or stricter controls, such as whitelisting destinations in production environments.

Additional options for Pre-Configured Proxies include:

Request and response transforms: Optionally use custom Node.js code to alter requests or responses, tokenize data from requests/responses, or append content to responses (JSON, text, or headers) — useful for specific cases, but not mandatory.
Configuration map: Store proxy-specific secrets, like API keys, securely.
Anonymous access: Permit requests without authentication if needed.

In production, Pre-Configured Proxies are often preferred for their ability to enforce defined settings. Transforms are available but not required—standard setups work just as well without them.

Create a Proxy

Creates a new Proxy for the Tenant.

POST

https://api.basistheory.com/proxies

Permissions

proxy:create

Request

transform='module.exports = async function (req) {
  // Do something with req.configuration.SERVICE_API_KEY

  return {
    headers: req.args.headers,
    body: req.args.body
  };
};'

curl "https://api.basistheory.com/proxies" \
  -H "BT-API-KEY: <MANAGEMENT_API_KEY>" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "name": "My Proxy",
    "destination_url": "https://example.com/api",
    "request_transforms": [
      {
        "code": '"$(echo $transform | jq -Rsa .)"'
      }
    ],
    "response_transforms": [
      {
        "code": '"$(echo $transform | jq -Rsa .)"'
      }
    ],
    "configuration": {
      "SERVICE_API_KEY": "key_abcd1234"
    },
    "application": {
      "id": "45c124e7-6ab2-4899-b4d9-1388b0ba9d04"
    },
    "require_auth": true
  }'

const proxy = await client.proxies.create({
    name: 'My Proxy',
    destinationUrl: 'https://example.com/api',
    requestTransforms: [
        {
            code: `
              module.exports = async function (req) {
                // Do something with req.configuration.SERVICE_API_KEY

                return {
                  headers: req.args.headers,
                  body: req.args.body
                };
              };
            `
        }
    ],
    responseTransforms: [
        {
            code: `
              module.exports = async function (req) {
                // Do something with req.configuration.SERVICE_API_KEY

                return {
                  headers: req.args.headers,
                  body: req.args.body
                };
              };
            `
        }
    ],
    configuration: {
        SERVICE_API_KEY: 'key_abcd1234',
    },
    application: {
        id: applicationId
    },
    requireAuth: true
});

import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('<MANAGEMENT_API_KEY>');

const proxy = await bt.proxies.create({
  name: 'My Proxy',
  destinationUrl: 'https://example.com/api',
  requestTransforms: [
    {
      code: `
        module.exports = async function (req) {
          // Do something with req.configuration.SERVICE_API_KEY

          return {
            headers: req.args.headers,
            body: req.args.body
          };
        };
      `
    }
  ],
  responseTransforms: [
    {
      code: `
        module.exports = async function (req) {
          // Do something with req.configuration.SERVICE_API_KEY

          return {
            headers: req.args.headers,
            body: req.args.body
          };
        };
      `
    }
  ],
  configuration: {
    SERVICE_API_KEY: 'key_abcd1234',
  },
  application: {
    id: '45c124e7-6ab2-4899-b4d9-1388b0ba9d04'
  },
  requireAuth: true
});

await client.Proxies.CreateAsync(new CreateProxyRequest
  {
      Name = "My Proxy",
      DestinationUrl = "https://example.com/api",
      RequestTransforms = new List<ProxyTransform>
      {
          new ProxyTransform
          {
              Code = @"
                module.exports = async function (req) {
                  // Do something with req.configuration.SERVICE_API_KEY

                  return {
                    headers: req.args.headers,
                    body: req.args.body
                  };
                };
              "
          }
      },
      ResponseTransforms = new List<ProxyTransform>
      {
          new ProxyTransform
          {
              Code = @"
                module.exports = async function (req) {
                  // Do something with req.configuration.SERVICE_API_KEY

                  return {
                    headers: req.args.headers,
                    body: req.args.body
                  };
                };
              "
          }
      },
      Configuration = new Dictionary<string, string?>
      {
          { "SERVICE_API_KEY", "key_abcd1234" }
      },
      Application = new Application
      {
          Id = applicationId
      },
      RequireAuth = true
  });

Proxy updatedProxy = new ProxiesClient(ClientOptions.builder().build())
                .update(Proxy.builder()
                        .id("id")
                        .name("My Proxy")
                        .destinationUrl("https://example.com/api")
                        .requestTransforms(List.of(
                                ProxyTransform.builder().code("module.exports = async function (req) { return { headers: req.args.headers, body: req.args.body }; };").build()
                        ))
                        .responseTransforms(List.of(
                                ProxyTransform.builder().code("module.exports = async function (req) { return { headers: req.args.headers, body: req.args.body }; };").build()
                        ))
                        .configuration(new HashMap<>())
                        .applicationId(applicationId)
                        .build());

client.proxies.create(
    name="My Proxy",
    destination_url="https://example.com/api",
    request_transforms=[
        {
            "code": """
                module.exports = async function (req) {
                  // Do something with req.configuration.SERVICE_API_KEY

                  return {
                    headers: req.args.headers,
                    body: req.args.body
                  };
                };
            """
        }
    ],
    response_transforms=[
        {
            "code": """
                module.exports = async function (req) {
                  // Do something with 'req.configuration.SERVICE_API_KEY'

                  return {
                    headers: req.args.headers,
                    body: req.args.body
                  };
                };
            """
        }
    ],
    configuration={
        "SERVICE_API_KEY": "key_abcd134"
    },
    application={
        "id": application_id
    },
    require_auth=True
)

transform := `module.exports = async function (req) {
  // Do something with req.configuration.SERVICE_API_KEY

  return {
    headers: req.args.headers,
    body: req.args.body
  };
};`

proxy, err := client.Proxies.Create(ctx, &basistheory.CreateProxyRequest{
    Name: "My Proxy",
    DestinationURL: "https://example.com/api",
    RequestTransforms: []*basistheory.ProxyTransform{
        { Code: &transform },
    },
    ResponseTransforms: []*basistheory.ProxyTransform{
        { Code: &transform },
    },
    Configuration: map[string]*string{
        "SERVICE_API_KEY": func(s string) *string { return &s }("key_abcd1234"),
    },
    Application: &basistheory.Application{
        ID: applicationID,
    },
    RequireAuth: true,
})

Request Parameters

Attribute	Required	Type	Default	Description
`name`	true	string	`null`	The name of the Proxy. Has a maximum length of `200`
`destination_url`	true	string	`null`	The URL to which requests will be proxied
`request_transforms`	false	array	`null`	One or more request transforms executed in order before sending to the destination.
`response_transforms`	false	array	`null`	One or more response transforms executed in order before returning the proxy response.
`application`	false	Application	`null`	This Application's API key is injected into a pre-configured BasisTheory JS SDK instance passed into the transform. Must be a `public` or `private` Application Type.
`configuration`	false	map<string, string>	`null`	A string key and string value map of all configuration name and values for a Proxy Transform
`require_auth`	false	boolean	`true`	Require a `BT-API-KEY` request header for authentication and authorization

Response

Returns a Proxy if the Proxy was created. Returns an error if there were validation errors, or the Proxy failed to create.

{
  "id": "433013a6-a614-4e1e-b2aa-5fba67aa85e6",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "name": "My Proxy",
  "key": "e29a50980ca5",
  "destination_url": "https://example.com/api",
  "request_transforms": [
    {
      "code": "
        module.exports = async function (req) {
          // Do something with req.configuration.SERVICE_API_KEY

          return {
            headers: req.args.headers,
            body: req.args.body
          };
        };
      "
    }
  ],
  "response_transforms": [
    {
      "code": "
        module.exports = async function (req) {
          // Do something with req.configuration.SERVICE_API_KEY

          return {
            headers: req.args.headers,
            body: req.args.body
          };
        };
      "
    }
  ],
  "configuration": {
    "SERVICE_API_KEY": "key_abcd1234"
  },
  "application_id": "45c124e7-6ab2-4899-b4d9-1388b0ba9d04",
  "require_auth": true,
  "created_by": "3ce0dceb-fd0b-4471-8006-c51243c9ef7a",
  "created_at": "2020-09-15T15:53:00+00:00"
}

List Proxies

Get a list of proxies for the Tenant.

GET

https://api.basistheory.com/proxies

Permissions

proxy:read

Request

curl "https://api.basistheory.com/proxies" \
  -H "BT-API-KEY: <MANAGEMENT_API_KEY>"

const response = await client.proxies.list();
for await (const item of response) {
    console.log(item);
}

// Or you can manually iterate page-by-page
const page = await client.proxies.list();
while (page.hasNextPage()) {
    page = page.getNextPage();
}

import { BasisTheory } from "@basis-theory/basis-theory-js";

const bt = await new BasisTheory().init("<MANAGEMENT_API_KEY>");

const proxies = await bt.proxies.list();

await client.Proxies.ListAsync(new ProxiesListRequest());

new ProxiesClient(ClientOptions.builder().build()).list();

response = client.proxies.list()

for item in response:
    yield item

# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

// List all proxies
proxies, err := client.Proxies.List(ctx, &basistheory.ProxiesListRequest{})

// List proxies with filters
proxies, err := client.Proxies.List(ctx, &basistheory.ProxiesListRequest{
	ID: []*string{
		func(s string) *string { return &s }("id1"),
		func(s string) *string { return &s }("id2"),
	},
	Name: "My Proxy",
})

Query Parameters

Parameter	Required	Type	Default	Description
`id`	false	array	`[]`	An optional list of Proxy ID's to filter the list of proxies by
`name`	false	string	`null`	Wildcard search of proxies by name

Response

Returns a paginated object with the data property containing an array of proxies. Providing any query parameters will filter the results. Returns an error if proxies could not be retrieved.

{
  "pagination": {...}
  "data": [
    {
      "id": "433013a6-a614-4e1e-b2aa-5fba67aa85e6",
      "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
      "name": "My Proxy",
      "key": "e29a50980ca5",
      "destination_url": "https://example.com/api",
      "request_transforms": [
        {
          "code": "
            module.exports = async function (req) {
              // Do something with req.configuration.SERVICE_API_KEY

              return {
                headers: req.args.headers,
                body: req.args.body
              };
            };
          "
        }
      ],
      "response_transforms": [
        {
          "code": "
            module.exports = async function (req) {
              // Do something with req.configuration.SERVICE_API_KEY

              return {
                headers: req.args.headers,
                body: req.args.body
              };
            };
          "
        }
      ],
      "configuration": {
        "SERVICE_API_KEY": "key_abcd1234"
      },
      "application_id": "45c124e7-6ab2-4899-b4d9-1388b0ba9d04",
      "require_auth": true,
      "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "created_at": "2020-09-15T15:53:00+00:00",
      "modified_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
      "modified_at": "2021-03-01T08:23:14+00:00"
    },
    {...},
    {...}
  ]
}

Get a Proxy

Get a Proxy by ID in the Tenant.

GET

https://api.basistheory.com/proxies/{id}

Permissions

proxy:read

Request

curl "https://api.basistheory.com/proxies/5b493235-6917-4307-906a-2cd6f1a90b13" \
  -H "BT-API-KEY: <MANAGEMENT_API_KEY>"

await client.proxies.get("id");

import { BasisTheory } from "@basis-theory/basis-theory-js";

const bt = await new BasisTheory().init("<MANAGEMENT_API_KEY>");

const proxy = await bt.proxies.retrieve("5b493235-6917-4307-906a-2cd6f1a90b13");

new ProxiesClient(ClientOptions.builder().build()).get("id");

client.proxies.get(
    id="id",
)

proxy, err := client.Proxies.Get(ctx, "id")

URI Parameters

Parameter	Required	Type	Default	Description
`id`	true	uuid	`null`	The ID of the proxy

Response

Returns a Proxy with the id provided. Returns an error if the Proxy could not be retrieved.

{
  "id": "433013a6-a614-4e1e-b2aa-5fba67aa85e6",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "name": "My Proxy",
  "key": "e29a50980ca5",
  "destination_url": "https://example.com/api",
  "request_transforms": [
    {
      "code": "
        module.exports = async function (req) {
          // Do something with req.configuration.SERVICE_API_KEY

          return {
            headers: req.args.headers,
            body: req.args.body
          };
        };
      "
    }
  ],
  "response_transforms": [
    {
      "code": "
        module.exports = async function (req) {
          // Do something with req.configuration.SERVICE_API_KEY

          return {
            headers: req.args.headers,
            body: req.args.body
          };
        };
      "
    }
  ],
  "configuration": {
    "SERVICE_API_KEY": "key_abcd1234"
  },
  "application_id": "45c124e7-6ab2-4899-b4d9-1388b0ba9d04",
  "require_auth": true,
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "modified_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "modified_at": "2021-03-01T08:23:14+00:00"
}

Update Proxy

Update a Proxy by ID in the Tenant.

PUT

https://api.basistheory.com/proxies/{id}

Permissions

proxy:update

Request

transform='module.exports = async function (req) {
  // Do something with req.configuration.SERVICE_API_KEY

  return {
    headers: req.args.headers,
    body: req.args.body
  };
};'

curl "https://api.basistheory.com/proxies/433013a6-a614-4e1e-b2aa-5fba67aa85e6" \
  -H "BT-API-KEY: <MANAGEMENT_API_KEY>" \
  -H "Content-Type: application/json" \
  -X "PUT" \
  -d '{
    "name": "My Proxy",
    "destination_url": "https://example.com/api",
    "request_transforms": [
      {
        "code": '"$(echo $transform | jq -Rsa .)"'
      }
    ],
    "response_transforms": [
      {
        "code": '"$(echo $transform | jq -Rsa .)"'
      }
    ],
    "configuration": {
      "SERVICE_API_KEY": "key_abcd1234"
    },
    "application": {
      "id": "45c124e7-6ab2-4899-b4d9-1388b0ba9d04"
    },
    "require_auth": true
  }'

await client.proxies.update(
    proxyId,
    {
    name: 'My Proxy',
    destinationUrl: 'https://example.com/api',
    requestTransforms: [
        {
            code: `
              module.exports = async function (req) {
                // Do something with req.configuration.SERVICE_API_KEY

                return {
                  headers: req.args.headers,
                  body: req.args.body
                };
              };
            `
        }
    ],
    responseTransforms: [
        {
            code: `
              module.exports = async function (req) {
                // Do something with req.configuration.SERVICE_API_KEY

                return {
                  headers: req.args.headers,
                  body: req.args.body
                };
              };
            `
        }
    ],
    configuration: {
        SERVICE_API_KEY: 'key_abcd1234',
    },
    application: {
        id: applicationId
    },
    requireAuth: true
});

import { BasisTheory } from '@basis-theory/basis-theory-js';

const bt = await new BasisTheory().init('<MANAGEMENT_API_KEY>');

const proxy = await bt.proxies.update('433013a6-a614-4e1e-b2aa-5fba67aa85e6', {
  name: 'My Proxy',
  destinationUrl: 'https://example.com/api',
  requestTransforms: [
    {
      code: `
        module.exports = async function (req) {
          // Do something with req.configuration.SERVICE_API_KEY

          return {
            headers: req.args.headers,
            body: req.args.body
          };
        };
      `
    }
  ],
  responseTransforms: [
    {
      code: `
        module.exports = async function (req) {
          // Do something with req.configuration.SERVICE_API_KEY

          return {
            headers: req.args.headers,
            body: req.args.body
          };
        };
      `
    }
  ],
  configuration: {
    SERVICE_API_KEY: 'key_abcd1234',
  },
  application: {
    id: '45c124e7-6ab2-4899-b4d9-1388b0ba9d04'
  },
  requireAuth: true
});

await client.Proxies.UpdateAsync(
    proxyId,
    new UpdateProxyRequest
    {
        Name = "My Proxy",
        DestinationUrl = "https://example.com/api",
        RequestTransforms = new List<ProxyTransform>
        {
            new ProxyTransform
            {
                Code = @"
              module.exports = async function (req) {
                // Do something with req.configuration.SERVICE_API_KEY

                return {
                  headers: req.args.headers,
                  body: req.args.body
                };
              };
            "
            }
        },
        ResponseTransforms = new List<ProxyTransform>
        {
            new ProxyTransform
            {
                Code = @"
              module.exports = async function (req) {
                // Do something with req.configuration.SERVICE_API_KEY

                return {
                  headers: req.args.headers,
                  body: req.args.body
                };
              };
            "
            }
        },
        Configuration = new Dictionary<string, string?>
        {
            { "SERVICE_API_KEY", "key_abcd1234" }
        },
        Application = new Application
        {
            Id = applicationId
        },
        RequireAuth = true
    }
);

Proxy updatedProxy = new ProxiesClient(ClientOptions.builder().build())
                .update(Proxy.builder()
                        .id("id")
                        .name("My Proxy")
                        .destinationUrl("https://example.com/api")
                        .requestTransforms(List.of(
                                ProxyTransform.builder().code("module.exports = async function (req) { return { headers: req.args.headers, body: req.args.body }; };").build()
                        ))
                        .responseTransforms(List.of(
                                ProxyTransform.builder().code("module.exports = async function (req) { return { headers: req.args.headers, body: req.args.body }; };").build()
                        ))
                        .configuration(new HashMap<>())
                        .applicationId(applicationId)
                        .build());

client.proxies.update(
    id=proxy_id,
    name="My Proxy",
    destination_url="https://example.com/api",
    request_transforms=[
        {
            "code": """
                    module.exports = async function (req) {
                      // Do something with req.configuration.SERVICE_API_KEY

                      return {
                        headers: req.args.headers,
                        body: req.args.body
                      };
                    };
                """
        }
    ],
    response_transforms=[
        {
            "code": """
                    module.exports = async function (req) {
                      // Do something with 'req.configuration.SERVICE_API_KEY'

                      return {
                        headers: req.args.headers,
                        body: req.args.body
                      };
                    };
                """
        }
    ],
    configuration={
        "SERVICE_API_KEY": "key_abcd134"
    },
    application={
        "id": application_id
    },
    require_auth=True
)

err := client.Proxies.Patch(ctx, "id", &basistheory.PatchProxyRequest{
    Name: "My Proxy",
    DestinationURL: "https://example.com/api",
    Configuration: map[string]string{
        "SERVICE_API_KEY": "key_abcd1234",
    },
})

URI Parameters

Parameter	Required	Type	Default	Description
`id`	true	uuid	`null`	The ID of the proxy

Request Parameters

Attribute	Required	Type	Default	Description
`name`	true	string	`null`	The name of the Proxy. Has a maximum length of `200`
`destination_url`	true	string	`null`	The URL to which requests will be proxied
`request_transforms`	false	array	`null`	One or more request transforms executed in order before sending to the destination.
`response_transforms`	false	array	`null`	One or more response transforms executed in order before returning the proxy response.
`application`	false	Application	`null`	This Application's API key is injected into a pre-configured BasisTheory JS SDK instance passed into the transform. Must be a `public` or `private` Application Type.
`configuration`	false	map<string, string>	`null`	A string key and string value map of all configuration name and values for a Proxy Transform
`require_auth`	false	boolean	`true`	Require a `BT-API-KEY` request header for authentication and authorization

Response

Returns a Proxy if the Proxy was updated. Returns an error if there were validation errors, or the Proxy failed to update.

{

  "id": "433013a6-a614-4e1e-b2aa-5fba67aa85e6",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "name": "My Proxy",
  "key": "e29a50980ca5",
  "destination_url": "https://example.com/api",
  "request_transforms": [
    {
      "code": "
        module.exports = async function (req) {
          // Do something with req.configuration.SERVICE_API_KEY

          return {
            headers: req.args.headers,
            body: req.args.body
          };
        };
      "
    }
  ],
  "response_transforms": [
    {
      "code": "
        module.exports = async function (req) {
          // Do something with req.configuration.SERVICE_API_KEY

          return {
            headers: req.args.headers,
            body: req.args.body
          };
        };
      "
    }
  ],
  "configuration": {
    "SERVICE_API_KEY": "key_abcd1234"
  },
  "application_id": "45c124e7-6ab2-4899-b4d9-1388b0ba9d04",
  "require_auth": true,
  "created_by": "3ce0dceb-fd0b-4471-8006-c51243c9ef7a",
  "created_at": "2020-09-15T15:53:00+00:00",
  "modified_by": "34053374-d721-43d8-921c-5ee1d337ef21",
  "modified_at": "2021-03-01T08:23:14+00:00"
}

Patch Proxy

Patch a Proxy by ID in the Tenant.

PATCH

https://api.basistheory.com/proxies/{id}

Permissions

proxy:update

The Patch Proxies endpoint uses a different content-type to support merge-patch operations. Requests need the Content-Type header to be set to application/merge-patch+json. Requests made with a different Content-Type header value will receive a 415 Unsupported Media Type response code. For more information on merge-patch, see RFC 7386.

Request

transform='module.exports = async function (req) {
// Do something with req.configuration.SERVICE_API_KEY

  return {
    headers: req.args.headers,
    body: req.args.body
  };
};'

curl "https://api.basistheory.com/proxies/433013a6-a614-4e1e-b2aa-5fba67aa85e6" \
-H "BT-API-KEY: <MANAGEMENT_API_KEY>" \
-H "Content-Type: application/merge-patch+json" \
-X "PATCH" \
-d '{
  "name": "My Proxy",
  "destination_url": "https://example.com/api",
  "configuration": {
    "SERVICE_API_KEY": "key_abcd1234"
  }
}'

await client.proxies.update(proxyId, {
    name: 'My Proxy',
    destinationUrl: "https://example.com/api",
    configuration: {
        SERVICE_API_KEY: "key_abcd1234",
    }
});

import { BasisTheory } from "@basis-theory/basis-theory-js";

const bt = await new BasisTheory().init("<MANAGEMENT_API_KEY>");

const proxy = await bt.proxies.patch("433013a6-a614-4e1e-b2aa-5fba67aa85e6", {
  name: "My Proxy",
  destinationUrl: "https://example.com/api",
  configuration: {
    SERVICE_API_KEY: "key_abcd1234",
  },
});

await client.Proxies.PatchAsync(
    proxyId,
    new PatchProxyRequest
    {
        Name = "My Proxy",
        DestinationUrl = "https://example.com/api",
        Configuration = new Dictionary<string, string?> {
            { "SERVICE_API_KEY", "key_abcd1234" }
        },
    }
);

Proxy patchedProxy = new ProxiesClient(ClientOptions.builder().build())
    .update("id", UpdateProxyRequest.builder()
        .name("My Proxy")
        .destinationUrl("https://example.com/api")
        .requestTransforms(List.of(
            ProxyTransform.builder().code("module.exports = async function (req) { return { headers: req.args.headers, body: req.args.body }; };").build()
        ))
        .responseTransforms(List.of(
            ProxyTransform.builder().code("module.exports = async function (req) { return { headers: req.args.headers, body: req.args.body }; };").build()
        ))
        .configuration(new HashMap<>())
        .build());

client.proxies.patch(
    id=proxy_id,
    name="(Deletable) python-SDK-" + str(uuid.uuid4()),
    destination_url="https://example.com/api",
    configuration={
        "SERVICE_API_KEY": "key_abcd134"
    }
)

err := client.Proxies.Patch(ctx, "id", &basistheory.PatchProxyRequest{
	Name: "My Proxy",
	DestinationURL: "https://example.com/api",
	Configuration: map[string]*string{
		"SERVICE_API_KEY": func(s string) *string { return &s }("key_abcd1234"),
	},
})

URI Parameters

Parameter	Required	Type	Default	Description
`id`	true	uuid	`null`	The ID of the proxy

Request Parameters

Attribute	Required	Type	Default	Description
`name`	false	string	`null`	The name of the Proxy. Has a maximum length of `200`
`destination_url`	false	string	`null`	The URL to which requests will be proxied
`request_transforms`	false	array	`null`	One or more request transforms executed in order before sending to the destination.
`response_transforms`	false	array	`null`	One or more response transforms executed in order before returning the proxy response.
`application`	false	Application	`null`	This Application's API key is injected into a pre-configured BasisTheory JS SDK instance passed into the transform. Must be a `public` or `private` Application Type.
`configuration`	false	map<string, string>	`null`	A string key and string value map of all configuration name and values for a Proxy Transform
`require_auth`	false	boolean	`true`	Require a `BT-API-KEY` request header for authentication and authorization

Response

Returns 204 if successful. Returns an error if there were validation errors, or the operation failed.

Delete Proxy

Delete a Proxy by ID in the Tenant.

DELETE

https://api.basistheory.com/proxies/{id}

Permissions

proxy:delete

Request

curl "https://api.basistheory.com/proxies/433013a6-a614-4e1e-b2aa-5fba67aa85e6" \
  -H "BT-API-KEY: <MANAGEMENT_API_KEY>" \
  -X "DELETE"

await client.proxies.delete("id");

import { BasisTheory } from "@basis-theory/basis-theory-js";

const bt = await new BasisTheory().init("<MANAGEMENT_API_KEY>");

await bt.proxies.delete("433013a6-a614-4e1e-b2aa-5fba67aa85e6");

await client.Proxies.DeleteAsync("id");

new ProxiesClient(ClientOptions.builder().build()).delete("id");

client.proxies.delete(
    id="id",
)

err := client.Proxies.Delete(ctx, "id")

URI Parameters

Parameter	Required	Type	Default	Description
`id`	true	uuid	`null`	The ID of the proxy

Response

Returns an error if the Proxy failed to delete.

Proxy Object

Attribute	Type	Description
`id`	uuid	Unique identifier of the Proxy which can be used to get a Proxy
`key`	string	Auto-generated key used to invoke this Proxy
`name`	string	The name of the Proxy
`destination_url`	string	The URL to which requests will be proxied
`tenant_id`	uuid	The Tenant ID which owns the Proxy
`require_auth`	boolean	Require a `BT-API-KEY` request header for authentication and authorization
`request_transforms`	array	(Optional) One or more request transforms executed in order before sending to the destination.
`response_transforms`	array	(Optional) One or more response transforms executed in order before returning the proxy response.
`application_id`	string	(Optional) This Application's API key is injected into a pre-configured BasisTheory JS SDK instance passed into the transform. Must be a `public` or `private` Application Type.
`configuration`	map<string, string>	(Optional) A string key and string value map of all configuration name and values for a Proxy Transform
`created_by`	uuid	(Optional) The ID of the user or Application that created the Proxy
`created_at`	string	(Optional) Created date of the Proxy in ISO 8601 format
`modified_by`	uuid	(Optional) The ID of the user or Application that last modified the Proxy
`modified_at`	date	(Optional) Last modified date of the Proxy in ISO 8601 format

Proxy Request Transform Object

Attribute	Type	Description
`type`	string	The type of request transform. One of `code` or `tokenize`. Default: `code`.
`code`	string	Transform code which will be executed when the Proxy transform is processed. Required when `type` is `code`. See Request Transforms for details.
`options`	object	Configuration options for the transform. Required when `type` is `tokenize`. See Transform Options for details.

Proxy Response Transform Object

See Response Transforms for details regarding the various types of response transforms.

Attribute	Type	Description
`type`	string	The type of response transform. One of `code`, `mask`, `tokenize`, `append_json`, `append_text`, or `append_header`. Default: `code`.
`code`	string	Transform code which will be executed when the Proxy transform is processed. Required when `type` is `code`
`options`	object	Configuration options for the transform. Required when `type` is `tokenize`, `append_json`, `append_text`, or `append_header`. See Transform Options for details.
`matcher`	string	The type of matching. One of `regex` or `chase_stratus_pan`. Required when `type` is `mask`
`replacement`	string	The replacement character for masking. Must be only one character in length. Required when `type` is `mask`
`expression`	string	The regular expression to use when determining masking values. Must contain at least one capture group using parenthesis. Required when `type` is `mask` and `matcher` is `regex`.

Transform Options

The options field structure varies by transform type:

Tokenize Transform Options (Request and Response)

Attribute	Type	Description
`token`	object	Token creation configuration matching the Create Token Request schema
`identifier`	string	Optional identifier for referencing the created token in subsequent transforms

For request and response transforms, token.data can contain:

Static plaintext values
Encrypted JWE expressions
Request expressions like "{{ req.card_number }}" or "{{ res.card_number }}" to extract data from the request or response payload

Append JSON Transform Options (Response only)

Attribute	Type	Description
`value`	any	The data to append to the response. Can contain Liquid expressions or token references
`location`	string	JSONPath expression specifying where to place the value in the response (e.g., `"$.created_token_id"`)

When using nested JSONPath expressions in the location field (e.g., "$.metadata.token_id"), the system will automatically create any missing parent objects in the response structure.

Append Text Transform Options (Response only)

Attribute	Type	Description
`value`	string	The text to append to the end of the response body. Can contain Liquid expressions or token references

Append Header Transform Options (Response only)

Attribute	Type	Description
`value`	string	The header value to add to the response. Can contain Liquid expressions or token references
`location`	string	The header name to add to the response

Token References in Options

For transforms that support token references, you can reference tokens created by previous transforms using:

"{{ transform_identifier: 'identifier' }}" - References the full token data
"{{ transform_identifier: 'identifier' | json: '$.path' }}" - Extracts specific data using JSONPath

Transforms

Pre-configured proxies support multiple transform types for processing requests and responses. Transforms are executed in the order specified in the array.

Transform Types

Request Transforms

code: Custom Node.js code executed in Basis Theory's serverless reactor environment
tokenize: Create tokens from request data using plaintext, encrypted JWE, or Liquid expressions

Response Transforms

code: Custom Node.js functions for complex response processing, tokenization, or detokenization
mask: Pattern-based masking using regex or predefined matchers
tokenize: Create tokens from response data using Liquid expressions or plaintext
append_json: Add JSON properties to response payload
append_text: Append plain text to response body
append_header: Add HTTP headers to responses

Testing and Dependencies

Testing transforms works the same as testing Reactors. Available NPM modules are listed here.

Whitelisted npm modules

You can find a list of all whitelisted NPM modules here.

Errors

Custom errors can be returned from request and response transforms by throwing reactor errors.

Any errors thrown from a transform will cause the proxy request to be terminated and the HTTP response to be immediately returned. In particular, errors thrown from a request transform will cause the proxy request to terminate before calling the destination API.

Reactor Errors

All pre-defined reactor error types, excluding errors of type CustomHttpResponseError, will be returned in their standard format and wrapped in a proxy_error property to distinguish these errors from destination API errors.

For example, a transform containing the following code:

const { AuthenticationError } = require('@basis-theory/basis-theory-reactor-formulas-sdk-js');

module.exports = async function (req) {
    const apiKey = req.args.headers['MY-CUSTOM-API-KEY'];

    if (!apiKey)
        throw new AuthenticationError('MY-CUSTOM-API-KEY header is required');

    // ...
}

would result in the following error response with a 401 status code if the MY-CUSTOM-API-KEY header is omitted:

{
    "proxy_error": {
        "errors": {
            "error": [
                "MY-CUSTOM-API-KEY header is required"
            ]
        },
        "title": "One or more validation errors occurred.",
        "status": 401,
        "detail": "Authentication Failed"
    }
}

Custom Errors

To provide more control over the errors returned from a proxy transform, a CustomHttpResponseError can be thrown from the transform. This will enable you to specify a status code, custom headers, and have complete control over the response body that is returned.

For example, a transform containing the following code:

const { CustomHttpResponseError } = require('@basis-theory/basis-theory-reactor-formulas-sdk-js');

module.exports = async function (req) {
  throw new CustomHttpResponseError({
    status: 400,
    headers: {
        "Custom-Response-Header-1": "custom-value-1",
        "Custom-Response-Header-2": "custom-value-2"
    },
    body: {
        myCustomError: "My custom error message"
    }
  });
};

results in an API response with status code 400, having the headers:

Custom-Response-Header-1: custom-value-1
Custom-Response-Header-2: custom-value-2

and the response body:

{
    "myCustomError": "My custom error message"
}

All transforms execute in array order. On the first error, remaining transforms are not executed, and the error response is returned.

Request Transforms

Request transforms process incoming HTTP requests before forwarding them to the destination. Available transform types:

code: Custom Node.js functions for complex request processing, header manipulation, or injecting proxy configuration secrets
tokenize: Create tokens from request data using plaintext values, encrypted expression, or Liquid expressions to extract data from the request

Code Request Transform

Code request transform is a Node.js v16 function executed in Basis Theory's serverless reactor environment:

module.exports = async function (req) {
  const { bt, args, configuration } = req;
  const { body, headers, method, path, query } = args; // access properties of the http request
  const { MY_CONFIG } = configuration; // access any static config defined on the Proxy

  // do anything here!
  const processedBody = ...; // do something with body
  const processedHeaders = ...; // do something with headers

  return {
      body: processedBody, // transformed request body
      headers: processedHeaders // transformed request headers
  };
};

Request Transform - Request Object

The request transform function receives the following object:

Attribute	Type	Description
`args`	object	Properties of the proxy request (see below)
`configuration`	object	The configuration defined for the Proxy object
`bt`	object	A pre-configured Basis Theory JS instance if an `application` was configured on the Proxy object
`applicationOptions`	object	An object containing configuration information about the `application` associated with the Proxy

where args contains:

Attribute	Type	Description
`body`	object or string	The request body parsed as a JavaScript `object` when `Content-Type` is `application/json`, or `string` for other content types.
`headers`	object	A JavaScript object containing the headers received on the proxy request
`method`	string	The HTTP method of the proxy request (e.g., "GET", "POST", "PUT", "PATCH", "DELETE")
`path`	string	The path suffix received on the proxy request after `/proxy` (e.g., a request to `/proxy/sub/path?param=value` would result in a `path` of `/sub/path`)
`query`	string	The unparsed query string that was received on the proxy request (e.g., a request to `/proxy/sub/path?param=value` would result in a `query` of `?param=value`)

and applicationOptions contains:

Attribute	Type	Description
`applicationOptions.apiKey`	string	The API key of the `application` associated with the Proxy. Useful to initialize `@basis-theory/node-sdk` or to make requests using an independent HTTP Client
`applicationOptions.environment`	string	The Basis Theory API URL for the `application` associated with the Proxy. Useful to initialize `@basis-theory/node-sdk` or to make requests using an independent HTTP Client

Request Transform - Response Object

An object of the following type must be returned by the request transform function:

Attribute	Type	Description
`body`	object	The transformed request body to forward to the destination
`headers`	object	The transformed request headers to forward to the destination

Tokenize Request Transform

Creates tokens from request data and makes them available for subsequent transforms via identifiers.

Basic Configuration:

{
  "type": "tokenize",
  "options": {
    "token": {
      "type": "token",
      "data": "sensitive_value"
    },
    "identifier": "my_token"
  }
}

Data Sources for token.data:

Plaintext: Static string values
Encrypted expression: "{{ encrypted | json: '$.data' }}" - Extract data from the header BT-ENCRYPTED
Request expressions: "{{ req.card_number }}" - Extract data from request properties

Token References: Created tokens can be referenced in subsequent transforms or the request body using:

"{{ transform_identifier: 'my_token' }}" - Full token data
"{{ transform_identifier: 'my_token' | json: '$.path' }}" - Extract specific data with JSONPath

Response Transforms

Response transforms process HTTP responses from the destination before returning them to the client.

Response transforms will only be executed when the destination returns a 2xx status code, and other non-2xx statuses will result in an immediate response from the proxy.

Code Response Transform

Code Response Transform can be used to:

Transform the body or headers on the HTTP response received from the destination before returning a response from the proxy
Tokenize sensitive values returned by a third party destination API
For inbound HTTP requests, tokens returned in responses from your system can be detokenized before sending the response to the third party caller

Code response transforms are Node.js v16 code blocks which export a function of the form:

module.exports = async function (req) {
  const { bt, args, configuration } = req;
  const { body, headers } = args; // access properties of the http response
  const { MY_CONFIG } = configuration; // access any static config defined on the Proxy

  // do anything here!
  const processedBody = ...; // do something to build a transformed body
  const processedHeaders = ...; // do something to build transformed headers

  return {
      body: processedBody, // transformed response body
      headers: processedHeaders // transformed request headers
  };
};

Code Response Transform - Javascript Request Object

The response transform function receives the following object:

Attribute	Type	Description
`args`	object	Properties of the proxy response (see below)
`configuration`	object	The configuration defined for the Proxy object
`bt`	object	A pre-configured Basis Theory JS instance if an `application` was configured on the Proxy object
`applicationOptions`	object	An object containing configuration information about the `application` associated with the Proxy

where args contains:

Attribute	Type	Description
`body`	object or string	The response body returned from the destination endpoint, parsed as a JavaScript `object` when `Content-Type` is `application/json`, or `string` for other content types.
`headers`	object	A JavaScript object containing the response headers returned from the destination endpoint

and applicationOptions contains:

Attribute	Type	Description
`applicationOptions.apiKey`	string	The API key of the `application` associated with the Proxy. Useful to initialize `@basis-theory/node-sdk` or to make requests using an independent HTTP Client
`applicationOptions.environment`	string	The Basis Theory API URL for the `application` associated with the Proxy. Useful to initialize `@basis-theory/node-sdk` or to make requests using an independent HTTP Client

Request header names are case-sensitive and can only contain alphanumeric characters, hyphens, and underscores. Headers names containing other characters will be discarded from the request. Response headers are unrestricted. If you must forward a restricted header to the proxy destination, as a workaround, you may add this header manually from within the request transform.

Code Response Transform - Javascript Response Object

An object of the following type must be returned by the response transform function:

Attribute	Type	Description
`body`	object	The transformed response body to return from the proxy
`headers`	object	The transformed response headers to return from the proxy

Mask Response Transform

Mask response transform can be used to transform the body of the response received from the destination before returning a response from the proxy. The mask transform has two available matcher types, regex and chase_stratus_pan.

Regex Matcher

Mask response transform using the regex matcher is defined using regular expressions and a replacement character.

{
    "name": "My masked proxy",
    "destination_url": "https://echo.basistheory.com/anything",
    "require_auth": false,
    "response_transform": {
        "type":"mask",
        "matcher":"regex",
        "replacement":"*",
        "expression":"\"accountNumber\":\\s*\"(.*?)\""
    }
}

The regular expression must contain at least one capture group. In the example above, the expression will capture the value of an accountNumber attribute of a JSON payload. Given the proxied service responds with a JSON similar to the following:

Original Response
{
    "username": "bsmith1486",
    "accountNumber": "56834512"
}

Then the sample proxy will mask the response as:

Transformed Response
{
    "username": "bsmith1486",
    "accountNumber": "********"
}

When a response body matches the given expression, the matched part of the body will be processed. During processing, any portion of the matched body section that is equivalent to any value of a capture group defined in the regex will be replaced. In this case, the matched body section is "accountNumber": "56834512".

The best practice is to limit the match scope to be as narrow as possible. There could be unintended or unexpected side effects if the match string is larger than necessary.

For example, given a regex defined as ^(aa).*?$, a match will occur when the line starts with "aa". However, since the regular expression uses the beginning, ^, and end $ syntax, the whole string will be matched and eligible for replacements. Given a response body of aabbccaabbccaa, the entire body will processed during masking. ALL values that match the capture group value, in this case aa, will be replaced. The response body will then be masked as **bbcc**bbcc**.

Chase Stratus PAN Matcher

If your proxy is interfacing with the Chase Stratus service, you may be able to take advantage of a default mask. The chase_stratus_pan matcher will automatically mask PANs from the Chase Stratus Account Verification and Tokenize responses.

{
    "name": "My Chase Stratus proxy",
    "destination_url": "<REPLACE WITH CHASE STATUS URL>",
    "require_auth": false,
    "response_transform": {
        "type":"mask",
        "matcher":"chase_stratus_pan",
        "replacement":"*",
    }
}

This mask will return responses as follows:

Account Verification

T74VKiwuJZ7TYGXD4navTHDLZG104240726tst844   *******************0929VI   000000000000CT01USANNXNNNXY\r

Tokenize

T74VEqMOciR1n8le3BhTVvl3zJ104240726         *******************0329DI   000000000000TI6559909009126557    \r

Tokenize Response Transform

Creates tokens from response data and makes them available for subsequent transforms via identifiers.

Basic Configuration:

{
  "type": "tokenize",
  "options": {
    "token": {
      "type": "token",
      "data": "{{ res.card_number }}"
    },
    "identifier": "response_token"
  }
}

Data Sources for token.data:

Plaintext: Static string values
Encrypted expression: "{{ encrypted | json: '$.data' }}" - Extract data from the header BT-ENCRYPTED
Response expressions: "{{ res.card_number }}" - Extract data from response properties

Append JSON Response Transform

Add JSON properties to response payload at specified locations using JSONPath expressions.

Basic Configuration:

{
  "type": "append_json",
  "options": {
    "value": "{{ transform_identifier: 'response_token' | json: '$.id' }}",
    "location": "$.created_token_id"
  }
}

Append Text Response Transform

Appends plain text content to the end of response body.

Basic Configuration:

{
  "type": "append_text",
  "options": {
    "value": "Token ID: {{ transform_identifier: 'response_token' | json: '$.id' }}"
  }
}

Append Header Response Transform

Add HTTP headers to response with values that can reference tokens from previous transforms.

Basic Configuration:

{
  "type": "append_header",
  "options": {
    "value": "{{ transform_identifier: 'response_token' | json: '$.id' }}",
    "location": "X-Token-ID"
  }
}

Token References in Response Transforms: All append transforms support referencing tokens created by previous transforms using:

"{{ transform_identifier: 'identifier' }}" - Full token data
"{{ transform_identifier: 'identifier' | json: '$.path' }}" - Extract specific data with JSONPath

Tokenizing or Detokenizing

In some situations, you may want to tokenize or detokenize data with Code Request Transform or Code Response Transform. In order to do this, set the application.id property when creating your Proxy with the id of an Application that has been granted the desired permissions. This will inject a Basis Theory JS instance into the transform request that is pre-configured for this application. For example:

module.exports = async function (req) {
  const token = await req.bt.tokenize({
    type: "token",
      data: req.args.body.sensitive_value,
    });

  req.args.body.sensitive_value = token.id;

  return {
    body: req.args.body,
    headers: req.args.headers,
  };
};

In the above example, we utilized the injected Basis Theory JS instance to tokenize a property called sensitive_value on our request body and passed the token back as the updated sensitive_value to be forwarded to the configured destination_url on our Proxy.

Create a Proxy​

Permissions​

Request​

Request Parameters​

Response​

List Proxies​

Permissions​

Request​

Query Parameters​

Response​

Get a Proxy​

Permissions​

Request​

URI Parameters​

Response​

Update Proxy​

Permissions​

Request​

URI Parameters​

Request Parameters​

Response​

Patch Proxy​

Permissions​

Request​

URI Parameters​

Request Parameters​

Response​

Delete Proxy​

Permissions​

Request​

URI Parameters​

Response​

Proxy Object​

Proxy Request Transform Object​

Proxy Response Transform Object​

Transform Options​

Tokenize Transform Options (Request and Response)​

Append JSON Transform Options (Response only)​

Append Text Transform Options (Response only)​

Append Header Transform Options (Response only)​

Token References in Options​

Transforms​

Transform Types​

Request Transforms​

Response Transforms​

Testing and Dependencies​

Whitelisted npm modules​

Errors​

Reactor Errors​

Custom Errors​

Request Transforms​

Code Request Transform​

Request Transform - Request Object​

Request Transform - Response Object​

Tokenize Request Transform​

Response Transforms​

Code Response Transform​

Code Response Transform - Javascript Request Object​

Code Response Transform - Javascript Response Object​

Mask Response Transform​

Regex Matcher​

Chase Stratus PAN Matcher​

Tokenize Response Transform​

Append JSON Response Transform​

Append Text Response Transform​

Append Header Response Transform​

Tokenizing or Detokenizing​

Create a Proxy

Permissions

Request

Request Parameters

Response

List Proxies

Permissions

Request

Query Parameters

Response

Get a Proxy

Permissions

Request

URI Parameters

Response

Update Proxy

Permissions

Request

URI Parameters

Request Parameters

Response

Patch Proxy

Permissions

Request

URI Parameters

Request Parameters

Response

Delete Proxy

Permissions

Request

URI Parameters

Response

Proxy Object

Proxy Request Transform Object

Proxy Response Transform Object

Transform Options

Tokenize Transform Options (Request and Response)

Append JSON Transform Options (Response only)

Append Text Transform Options (Response only)

Append Header Transform Options (Response only)

Token References in Options

Transforms

Transform Types

Request Transforms

Response Transforms

Testing and Dependencies

Whitelisted npm modules

Errors

Reactor Errors

Custom Errors

Request Transforms

Code Request Transform

Request Transform - Request Object

Request Transform - Response Object

Tokenize Request Transform

Response Transforms

Code Response Transform

Code Response Transform - Javascript Request Object

Code Response Transform - Javascript Response Object

Mask Response Transform

Regex Matcher

Chase Stratus PAN Matcher

Tokenize Response Transform

Append JSON Response Transform

Append Text Response Transform

Append Header Response Transform

Tokenizing or Detokenizing