Pre-Configured Proxies

As an alternative to the Ephemeral Proxy, the Basis Theory Proxy also supports pre-configuring proxy instances before they are invoked. This can be useful to reuse common configurations across requests, or to accept inbound HTTP requests from third parties. When using a proxy to accept inbound requests from third parties, pre-configured proxies allow you to define the proxy's behavior and simply share that proxy's unique URL with the third party integrator.

Pre-configured proxies also support additional configuration options, including:

• Request and response transforms to invoke custom code during the request pipeline
• Securely storing proxy-specific secrets within a configuration map
• Allowing anonymous proxy requests

Create a Proxy

Creates a new Proxy for the Tenant.

POST

https://api.basistheory.com/proxies

Permissions

proxy:create

Request

cURL

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_transform": {
      "code": '"$(echo $transform | jq -Rsa .)"',
    },
    "response_transform": {
      "code": '"$(echo $transform | jq -Rsa .)"',
    },
    "configuration": {
      "SERVICE_API_KEY": "key_abcd1234"
    },
    "application": {
      "id": "45c124e7-6ab2-4899-b4d9-1388b0ba9d04"
    },
    "require_auth": true
  }'

JavaScript

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',
  requestTransform: {
    code: '
      module.exports = async function (req) {
        // Do something with req.configuration.SERVICE_API_KEY

        return {
          headers: req.args.headers,
          body: req.args.body
        };
      };
    '
  },
  responseTransform: {
    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
});

C#

using BasisTheory.net.Proxies;

var client = new ProxyClient("<MANAGEMENT_API_KEY>");

var proxy = await client.CreateAsync(new ProxyCreateRequest {
  Name = "My Proxy",
  DestinationUrl = "https://example.com/api",
  RequestTransform = 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
        };
      };
    "
  },
  ResponseTransform = 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 = new Guid("45c124e7-6ab2-4899-b4d9-1388b0ba9d04")
  },
  RequireAuthentication = true
});

Java

import com.basistheory.*;
import com.basistheory.auth.*;
import java.util.Map;
import java.util.UUID;

public class Example {
    public static void main(String[] args) throws Exception {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("https://api.basistheory.com");

        ApiKeyAuth ApiKey = (ApiKeyAuth) defaultClient.getAuthentication("ApiKey");
        ApiKey.setApiKey("<MANAGEMENT_API_KEY>");

        ProxiesApi apiInstance = new ProxiesApi(defaultClient);
        CreateProxyRequest createProxyRequest = new CreateProxyRequest();
        Proxy result = apiInstance.create(createProxyRequest
                .name("My Proxy")
                .destinationUrl("https://example.com/api")
                .requestTransform(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
                                };
                              };
                        """))
                .responseTransform(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(Map.of("SERVICE_API_KEY", "key_abcd1234"))
                .application(new Application().id(UUID.fromString("45c124e7-6ab2-4899-b4d9-1388b0ba9d04")))
                .requireAuth(true));
    }
}

Python

import basistheory
from basistheory.api import proxies_api
from basistheory.model.create_proxy_request import CreateProxyRequest

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="<MANAGEMENT_API_KEY>")) as api_client:
    proxy_client = proxies_api.ProxiesApi(api_client)

    proxy = proxy_client.create(create_proxy_request=CreateProxyRequest(
        name="My Proxy",
        destination_url="https://example.com/api",
        requeset_transform=ProxyTransform(
            code=" \
                module.exports = async function (req) { \
                  // Do something with req.configuration.SERVICE_API_KEY \

                  return { \
                    headers: req.args.headers, \
                    body: req.args.body \
                  }; \
                };"
        ),
        response_transform=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={
            "SERVICE_API_KEY": "key_abcd134"
        },
        application=Application(
            id="45c124e7-6ab2-4899-b4d9-1388b0ba9d04"
        ),
        require_auth=True
    ))

Go

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "<MANAGEMENT_API_KEY>"},
  })

  createProxyRequest := *basistheory.NewCreateProxyRequest("My Proxy", "https://example.com/api")
  requestTransform := *basistheory.NewProxyTransform()
  requestTransform.SetCode(`
    module.exports = async function (req) {
      // Do something with req.configuration.SERVICE_API_KEY

      return {
        headers: req.args.headers,
        body: req.args.body
      };
    };
  `)
  createProxyRequest.SetRequestTransform(requestTransform)
  responseTransform := *basistheory.NewProxyTransform()
  responseTransform.SetCode(`
    module.exports = async function (req) {
      // Do something with req.configuration.SERVICE_API_KEY

      return {
        headers: req.args.headers,
        body: req.args.body
      };
    };
  `)
  createProxyRequest.SetResponseTransform(responseTransform)
  createProxyRequest.SetConfiguration(map[string]string{
    "SERVICE_API_KEY": "key_abcd134",
  })
  application := *basistheory.NewApplication()
  application.SetId("45c124e7-6ab2-4899-b4d9-1388b0ba9d04")
  createProxyRequest.SetApplication(application)
  createProxyRequest.SetRequireAuth(true)

  proxy, httpResponse, err := apiClient.ProxiesApi.Create(contextWithAPIKey).CreateProxyRequest(createProxyRequest).Execute()
}

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_transform	false	Proxy Transform	null	Request Transform which will be executed against the proxy request before sending to the destination.
response_transform	false	Proxy Transform	null	Response Transform which will be executed against the destination's response 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	null	A key-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_transform": {
    "code": "
      module.exports = async function (req) {
        // Do something with req.configuration.SERVICE_API_KEY

        return {
          headers: req.args.headers,
          body: req.args.body
        };
      };
    "
  },
  "response_transform": {
    "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

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

JavaScript

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

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

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

C#

using BasisTheory.net.Proxies;

var client = new ProxyClient("<MANAGEMENT_API_KEY>");

var proxies = await client.GetAsync();

Java

import com.basistheory.*;
import com.basistheory.auth.*;
import java.util.Arrays;
import java.util.List;
import java.util.UUID;

public class Example {
    public static void main(String[] args) throws Exception {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("https://api.basistheory.com");

        ApiKeyAuth ApiKey = (ApiKeyAuth) defaultClient.getAuthentication("ApiKey");
        ApiKey.setApiKey("<MANAGEMENT_API_KEY>");

        ProxiesApi apiInstance = new ProxiesApi(defaultClient);
        List<UUID> id = Arrays.asList();
        String name = "name_example";
        Integer page = 1;
        Integer size = 50;
        ProxyPaginatedList result = apiInstance.get(id, name, page, size);
    }
}

Python

import basistheory
from basistheory.api import proxies_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="<MANAGEMENT_API_KEY>")) as api_client:
    proxy_client = proxies_api.ProxiesApi(api_client)

    proxies = proxy_client.get()

Go

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "<MANAGEMENT_API_KEY>"},
  })

  proxies, httpResponse, err := apiClient.ProxiesApi.Get(contextWithAPIKey).Execute()
}

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_transform": {
        "code": "
          module.exports = async function (req) {
            // Do something with req.configuration.SERVICE_API_KEY

            return {
              headers: req.args.headers,
              body: req.args.body
            };
          };
        "
      },
      "response_transform": {
        "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

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

JavaScript

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");

C#

using BasisTheory.net.Proxies;

var client = new ProxyClient("<MANAGEMENT_API_KEY>");

var proxy = await client.GetByIdAsync("5b493235-6917-4307-906a-2cd6f1a90b13");

Java

import com.basistheory.*;
import com.basistheory.auth.*;
import java.util.Arrays;
import java.util.List;
import java.util.UUID;

public class Example {
    public static void main(String[] args) throws Exception {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("https://api.basistheory.com");

        ApiKeyAuth ApiKey = (ApiKeyAuth) defaultClient.getAuthentication("ApiKey");
        ApiKey.setApiKey("<MANAGEMENT_API_KEY>");

        ProxiesApi apiInstance = new ProxiesApi(defaultClient);
        Proxy result = apiInstance.getById(UUID.fromString("5b493235-6917-4307-906a-2cd6f1a90b13"));
    }
}

Python

import basistheory
from basistheory.api import proxies_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="<MANAGEMENT_API_KEY>")) as api_client:
    proxy_client = proxies_api.ProxiesApi(api_client)

    application = proxy_client.get_by_id("5b493235-6917-4307-906a-2cd6f1a90b13")

Go

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "<MANAGEMENT_API_KEY>"},
  })

  proxy, httpResponse, err := apiClient.ProxiesApi.GetById(contextWithAPIKey, "433013a6-a614-4e1e-b2aa-5fba67aa85e6").Execute()
}

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_transform": {
    "code": "
      module.exports = async function (req) {
        // Do something with req.configuration.SERVICE_API_KEY

        return {
          headers: req.args.headers,
          body: req.args.body
        };
      };
    "
  },
  "response_transform": {
    "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

cURL

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_transform": {
      "code": '"$(echo $transform | jq -Rsa .)"',
    },
    "response_transform": {
      "code": '"$(echo $transform | jq -Rsa .)"',
    },
    "configuration": {
      "SERVICE_API_KEY": "key_abcd1234"
    },
    "application": {
      "id": "45c124e7-6ab2-4899-b4d9-1388b0ba9d04"
    },
    "require_auth": true
  }'

JavaScript

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',
  requestTransform: {
    code: '
      module.exports = async function (req) {
        // Do something with req.configuration.SERVICE_API_KEY

        return {
          headers: req.args.headers,
          body: req.args.body
        };
      };
    '
  },
  responseTransform: {
    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
});

C#

using BasisTheory.net.Proxies;

var client = new ProxyClient("<MANAGEMENT_API_KEY>");

var proxy = await client.UpdateAsync("433013a6-a614-4e1e-b2aa-5fba67aa85e6",
  new ProxyUpdateRequest {
    Name = "My Proxy",
    DestinationUrl = "https://example.com/api",
    RequestTransform = 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
          };
        };
      "
    },
    ResponseTransform = 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 = new Guid("45c124e7-6ab2-4899-b4d9-1388b0ba9d04")
    },
    RequireAuthentication = true
  });

Java

import com.basistheory.*;
import com.basistheory.auth.*;
import java.util.Map;
import java.util.UUID;

public class Example {
    public static void main(String[] args) throws Exception {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("https://api.basistheory.com");

        ApiKeyAuth ApiKey = (ApiKeyAuth) defaultClient.getAuthentication("ApiKey");
        ApiKey.setApiKey("<MANAGEMENT_API_KEY>");

        ProxiesApi apiInstance = new ProxiesApi(defaultClient);
        UpdateProxyRequest updateProxyRequest = new UpdateProxyRequest();
        Proxy result = apiInstance.update("433013a6-a614-4e1e-b2aa-5fba67aa85e6", updateProxyRequest
                .name("My Proxy")
                .destinationUrl("https://example.com/api")
                .requestTransform(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
                                };
                              };
                        """))
                .responseTransform(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(Map.of("SERVICE_API_KEY", "key_abcd1234"))
                .application(new Application().id(UUID.fromString("45c124e7-6ab2-4899-b4d9-1388b0ba9d04")))
                .requireAuth(true));
    }
}

Python

import basistheory
from basistheory.api import proxies_api
from basistheory.model.update_proxy_request import UpdateProxyRequest

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="<MANAGEMENT_API_KEY>")) as api_client:
    proxy_client = proxies_api.ProxiesApi(api_client)

    application = proxy_client.update("433013a6-a614-4e1e-b2aa-5fba67aa85e6", update_proxy_request=UpdateProxyRequest(
        name="My Proxy",
        destination_url="https://example.com/api",
        requeset_transform=ProxyTransform(
            code=" \
                module.exports = async function (req) { \
                  // Do something with req.configuration.SERVICE_API_KEY \

                  return { \
                    headers: req.args.headers, \
                    body: req.args.body \
                  }; \
                };"
        ),
        response_transform=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={
            "SERVICE_API_KEY": "key_abcd134"
        },
        application=Application(
            id="45c124e7-6ab2-4899-b4d9-1388b0ba9d04"
        ),
        require_auth=True
    ))

Go

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "<MANAGEMENT_API_KEY>"},
  })

  updateProxyRequest := *basistheory.NewUpdateProxyRequest("My Proxy", "https://example.com/api")
  requestTransform := *basistheory.NewProxyTransform()
  requestTransform.SetCode(`
    module.exports = async function (req) {
      // Do something with req.configuration.SERVICE_API_KEY

      return {
        headers: req.args.headers,
        body: req.args.body
      };
    };
  `)
  updateProxyRequest.SetRequestTransform(requestTransform)
  responseTransform := *basistheory.NewProxyTransform()
  responseTransform.SetCode(`
    module.exports = async function (req) {
      // Do something with req.configuration.SERVICE_API_KEY

      return {
        headers: req.args.headers,
        body: req.args.body
      };
    };
  `)
  updateProxyRequest.SetResponseTransform(responseTransform)
  updateProxyRequest.SetConfiguration(map[string]string{
    "SERVICE_API_KEY": "key_abcd134",
  })
  application := *basistheory.NewApplication()
  application.SetId("45c124e7-6ab2-4899-b4d9-1388b0ba9d04")
  updateProxyRequest.SetApplication(application)
  updateProxyRequest.SetRequireAuth(true)

  proxy, httpResponse, err := apiClient.ProxiesApi.Update(contextWithAPIKey, "433013a6-a614-4e1e-b2aa-5fba67aa85e6").UpdateProxyRequest(updateProxyRequest).Execute()
}

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_transform	false	Proxy Transform	null	Request Transform which will be executed against the proxy request before sending to the destination.
response_transform	false	Proxy Transform	null	Response Transform which will be executed against the destination's response 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	null	A key-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_transform": {
    "code": "
      module.exports = async function (req) {
        // Do something with req.configuration.SERVICE_API_KEY

        return {
          headers: req.args.headers,
          body: req.args.body
        };
      };
    "
  },
  "response_transform": {
    "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

cURL

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"
  }
}'

JavaScript

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",
  },
});

C#

using BasisTheory.net.Proxies;

var client = new ProxyClient("<MANAGEMENT_API_KEY>");

var proxy = await client.PatchAsync("433013a6-a614-4e1e-b2aa-5fba67aa85e6",
  new ProxyPatchRequest {
    Name = "My Proxy",
    DestinationUrl = "https://example.com/api",
    Configuration = new Dictionary<string, string> {
      { "SERVICE_API_KEY", "key_abcd1234" }
    }
  });

Java

import com.basistheory.*;
import com.basistheory.auth.*;
import java.util.Map;
import java.util.UUID;

public class Example {
  public static void main(String[] args) throws Exception {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("https://api.basistheory.com");

    ApiKeyAuth ApiKey = (ApiKeyAuth) defaultClient.getAuthentication("ApiKey");
    ApiKey.setApiKey("<MANAGEMENT_API_KEY>");

    ProxiesApi apiInstance = new ProxiesApi(defaultClient);
    PatchProxyRequest patchProxyRequest = new PatchProxyRequest();
    Proxy result = apiInstance.create("433013a6-a614-4e1e-b2aa-5fba67aa85e6", patchProxyRequest
      .name("My Proxy")
      .destinationUrl("https://example.com/api")
      ._configuration(Map.of("SERVICE_API_KEY", "key_abcd1234")));
  }
}

Python

import basistheory
from basistheory.api import proxies_api
from basistheory.model.patch_proxy_request import PatchProxyRequest

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="<MANAGEMENT_API_KEY>")) as api_client:
proxy_client = proxies_api.ProxiesApi(api_client)

application = proxy_client.update("433013a6-a614-4e1e-b2aa-5fba67aa85e6", update_proxy_request=UpdateProxyRequest(
  name="My Proxy",
  destination_url="https://example.com/api",
  configuration={
    "SERVICE_API_KEY": "key_abcd134"
  })

Go

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "<MANAGEMENT_API_KEY>"},
  })

  patchProxyRequest := *basistheory.NewPatchProxyRequest("My Proxy", "https://example.com/api")
  patchProxyRequest.SetConfiguration(map[string]string{
    "SERVICE_API_KEY": "key_abcd134",
  })
  application := *basistheory.NewApplication()
  application.SetId("45c124e7-6ab2-4899-b4d9-1388b0ba9d04")

  proxy, httpResponse, err := apiClient.ProxiesApi.Patch(contextWithAPIKey, "433013a6-a614-4e1e-b2aa-5fba67aa85e6").PatchProxyRequest(patchProxyRequest).Execute()
}

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_transform	false	Proxy Transform	null	Request Transform which will be executed against the proxy request before sending to the destination.
response_transform	false	Proxy Transform	null	Response Transform which will be executed against the destination's response 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	null	A key-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

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

JavaScript

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");

C#

using BasisTheory.net.Proxies;

var client = new ProxyClient("<MANAGEMENT_API_KEY>");

await client.DeleteAsync("433013a6-a614-4e1e-b2aa-5fba67aa85e6");

Java

import com.basistheory.*;
import com.basistheory.auth.*;
import java.util.UUID;

public class Example {
    public static void main(String[] args) throws Exception {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("https://api.basistheory.com");

        ApiKeyAuth ApiKey = (ApiKeyAuth) defaultClient.getAuthentication("ApiKey");
        ApiKey.setApiKey("<MANAGEMENT_API_KEY>");

        ProxiesApi apiInstance = new ProxiesApi(defaultClient);
        apiInstance.delete(UUID.fromString("5b493235-6917-4307-906a-2cd6f1a90b13"));
    }
}

Python

import basistheory
from basistheory.api import proxies_api

with basistheory.ApiClient(configuration=basistheory.Configuration(api_key="<MANAGEMENT_API_KEY>")) as api_client:
    proxies_client = proxies_api.ProxiesApi(api_client)

    proxies_client.delete("433013a6-a614-4e1e-b2aa-5fba67aa85e6")

Go

package main

import (
  "context"
  "github.com/Basis-Theory/basistheory-go/v3"
)

func main() {
  configuration := basistheory.NewConfiguration()
  apiClient := basistheory.NewAPIClient(configuration)
  contextWithAPIKey := context.WithValue(context.Background(), basistheory.ContextAPIKeys, map[string]basistheory.APIKey{
    "ApiKey": {Key: "<MANAGEMENT_API_KEY>"},
  })

  httpResponse, err := apiClient.ProxiesApi.Delete(contextWithAPIKey, "433013a6-a614-4e1e-b2aa-5fba67aa85e6").Execute()
}

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_transform	Proxy Transform	(Optional) Request Transform which will be executed against the proxy request before sending to the destination.
response_transform	Proxy Transform	(Optional) Response Transform which will be executed against the destination's response 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	(Optional) A key-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 Transform Object

Attribute	Type	Description
code	string	Transform code which will be executed when the Proxy transform is processed. See Request Transforms or Response Transforms for details.

Invoke a Proxy

Invoke a pre-configured proxy instance.

POST

https://api.basistheory.com/proxy

GET

https://api.basistheory.com/proxy

PUT

https://api.basistheory.com/proxy

PATCH

https://api.basistheory.com/proxy

DELETE

https://api.basistheory.com/proxy

Authentication

Pre-configured proxies can be configured to either require authentication or allow anonymous requests. When authentication is required, a BT-API-KEY header must be provided with the request (see Authentication).

Unauthenticated proxy requests may be desired when receiving inbound requests from a third party. This would allow any caller who knows your unique proxy key to make inbound requests through the proxy without needing to share a Basis Theory API key with third parties.

Any authentication required by the destination service can be set on the request and will be forwarded through the proxy (for example, by setting an Authorization header).

Permissions

token:use

The token:use permission is required for each Container of Tokens you wish to detokenize through the Proxy. This permission is required to use authenticated proxies, even if there are no tokens being detokenized within your request.

It is recommended that you restrict which tokens the Proxy can detokenize by only granting token:use permission on the most-specific container of tokens that is required.

Reserved Proxy Headers

Enterprise

Proxies also include the ability to turn on additional features during a request, below outlines how to take advantage of each

Header	Description
BT-PROXY-KEEP-ALIVE	Injects header value into KEEP-ALIVE header when calling destination url
BT-PROXY-CONNECTION	Injects header value into CONNECTION header when calling destination url

Request

The unique key for a pre-configured proxy can either be supplied in a request header or a query string parameter.

Request with 'BT-PROXY-KEY' header

curl "https://api.basistheory.com/proxy" \
  -H "BT-API-KEY: <PRIVATE_API_KEY>" \
  -H "BT-PROXY-KEY: e29a50980ca5" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "parameter1": "{{26818785-547b-4b28-b0fa-531377e99f4e}}",
    "parameter2": "non-sensitive"
  }'

Request with 'bt-proxy-key' query param

curl "https://api.basistheory.com/proxy?bt-proxy-key=e29a50980ca5" \
  -H "BT-API-KEY: <PRIVATE_API_KEY>" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "parameter1": "{{26818785-547b-4b28-b0fa-531377e99f4e}}",
    "parameter2": "non-sensitive"
  }'

Response

The raw response from the destination will be returned from the proxy, unless an error occurs within the Basis Theory Proxy while processing the request.

If an error occurs within the proxy (e.g. an invalid detokenization expression was found), then the following error response will be returned:

Attribute	Type	Description
proxy_error	any	A standard Basis Theory error

Custom Headers

Header	Description
BT-PROXY-DESTINATION-STATUS	This header contains the HTTP status code from the destination server.

If the BT-PROXY-DESTINATION-STATUS HTTP header is present and has an HTTP status code, the code represents the status code responded from the destination service. A 4xx code generally points to a problem with the integration to the destination, while a 5xx code suggests an issue with the destination service itself.

If the BT-PROXY-DESTINATION-STATUS HTTP header is not present, there is likely an integration or service problem. 4xx codes indicate issues on your end, while 5xx codes indicate problems with Basis Theory's service.

Transforms

Pre-configured proxies allow you to optionally define request or response transforms, which allow custom Node.js code to be executed before and after the HTTP request is forwarded to the destination URL. When a transform is defined on a proxy, your custom Node.js code will execute in Basis Theory's secure serverless reactor environment.

The maximum payload size to invoke a Pre-configured proxy which uses a Transform is 5 MB. You could pull in more data using the injected BT client from within the Transform code. Please reach out if you need help.

Testing

Testing Transforms works the same as testing Reactors.

Whitelisted npm modules

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

Request Transforms

Request Transforms can be used to:

• Transform the body or headers on the HTTP request before forwarding the request to the destination
• Tokenize parts of an inbound HTTP request and replace sensitive data with tokens before it hits your systems
• Inject secrets that are configured within the proxy (e.g. third party API credentials) into the request body or headers

Request 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, 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

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)

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

Response Transforms

Response Transforms 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

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
  };
};

Response Transform - 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

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

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.

Response Transform - 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

Tokenizing or Detokenizing

In some situations, you may want to tokenize or detokenize data within a 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.

Errors

Please refer to Proxy Transform Errors for the full documentation around handling and returning errors from proxy transforms.