Skip to main content

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
Copy

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

Request Parameters

AttributeRequiredTypeDefaultDescription
nametruestringnullThe name of the Proxy. Has a maximum length of 200
destination_urltruestringnullThe URL to which requests will be proxied
request_transformfalseProxy TransformnullRequest Transform which will be executed against the proxy request before sending to the destination.
response_transformfalseProxy TransformnullResponse Transform which will be executed against the destination's response before returning the proxy response.
applicationfalseApplicationnullThis 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.
configurationfalsemapnullA key-value map of all configuration name and values for a Proxy Transform
require_authfalsebooleantrueRequire 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
Copy

Permissions

proxy:read

Request

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

Query Parameters

ParameterRequiredTypeDefaultDescription
idfalsearray[]An optional list of Proxy ID's to filter the list of proxies by
namefalsestringnullWildcard 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}
Copy

Permissions

proxy:read

Request

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

URI Parameters

ParameterRequiredTypeDefaultDescription
idtrueuuidnullThe 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}
Copy

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

URI Parameters

ParameterRequiredTypeDefaultDescription
idtrueuuidnullThe ID of the proxy

Request Parameters

AttributeRequiredTypeDefaultDescription
nametruestringnullThe name of the Proxy. Has a maximum length of 200
destination_urltruestringnullThe URL to which requests will be proxied
request_transformfalseProxy TransformnullRequest Transform which will be executed against the proxy request before sending to the destination.
response_transformfalseProxy TransformnullResponse Transform which will be executed against the destination's response before returning the proxy response.
applicationfalseApplicationnullThis 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.
configurationfalsemapnullA key-value map of all configuration name and values for a Proxy Transform
require_authfalsebooleantrueRequire 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}
Copy

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

URI Parameters

ParameterRequiredTypeDefaultDescription
idtrueuuidnullThe ID of the proxy

Request Parameters

AttributeRequiredTypeDefaultDescription
namefalsestringnullThe name of the Proxy. Has a maximum length of 200
destination_urlfalsestringnullThe URL to which requests will be proxied
request_transformfalseProxy TransformnullRequest Transform which will be executed against the proxy request before sending to the destination.
response_transformfalseProxy TransformnullResponse Transform which will be executed against the destination's response before returning the proxy response.
applicationfalseApplicationnullThis 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.
configurationfalsemapnullA key-value map of all configuration name and values for a Proxy Transform
require_authfalsebooleantrueRequire 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}
Copy

Permissions

proxy:delete

Request

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

URI Parameters

ParameterRequiredTypeDefaultDescription
idtrueuuidnullThe ID of the proxy

Response

Returns an error if the Proxy failed to delete.

Proxy Object

AttributeTypeDescription
iduuidUnique identifier of the Proxy which can be used to get a Proxy
keystringAuto-generated key used to invoke this Proxy
namestringThe name of the Proxy
destination_urlstringThe URL to which requests will be proxied
tenant_iduuidThe Tenant ID which owns the Proxy
require_authbooleanRequire a BT-API-KEY request header for authentication and authorization
request_transformProxy Transform(Optional) Request Transform which will be executed against the proxy request before sending to the destination.
response_transformProxy Transform(Optional) Response Transform which will be executed against the destination's response before returning the proxy response.
application_idstring(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.
configurationmap(Optional) A key-value map of all configuration name and values for a Proxy Transform
created_byuuid(Optional) The ID of the user or Application that created the Proxy
created_atstring(Optional) Created date of the Proxy in ISO 8601 format
modified_byuuid(Optional) The ID of the user or Application that last modified the Proxy
modified_atdate(Optional) Last modified date of the Proxy in ISO 8601 format

Proxy Transform Object

AttributeTypeDescription
codestringTransform 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
Copy
GET
https://api.basistheory.com/proxy
Copy
PUT
https://api.basistheory.com/proxy
Copy
PATCH
https://api.basistheory.com/proxy
Copy
DELETE
https://api.basistheory.com/proxy
Copy

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

HeaderDescription
BT-PROXY-KEEP-ALIVEInjects header value into KEEP-ALIVE header when calling destination url
BT-PROXY-CONNECTIONInjects 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:

AttributeTypeDescription
proxy_erroranyA standard Basis Theory error

Custom Headers

HeaderDescription
BT-PROXY-DESTINATION-STATUSThis 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:

AttributeTypeDescription
argsobjectProperties of the proxy request (see below)
configurationobjectThe configuration defined for the Proxy object
btobjectA pre-configured Basis Theory JS instance if an application was configured on the Proxy object

where args contains:

AttributeTypeDescription
bodyobject or stringThe request body parsed as a JavaScript object when Content-Type is application/json, or string for other content types.
headersobjectA JavaScript object containing the headers received on the proxy request
methodstringThe HTTP method of the proxy request (e.g., "GET", "POST", "PUT", "PATCH", "DELETE")
pathstringThe 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)
querystringThe 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:

AttributeTypeDescription
bodyobjectThe transformed request body to forward to the destination
headersobjectThe 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:

AttributeTypeDescription
argsobjectProperties of the proxy response (see below)
configurationobjectThe configuration defined for the Proxy object
btobjectA pre-configured Basis Theory JS instance if an application was configured on the Proxy object

where args contains:

AttributeTypeDescription
bodyobject or stringThe response body returned from the destination endpoint, parsed as a JavaScript object when Content-Type is application/json, or string for other content types.
headersobjectA 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:

AttributeTypeDescription
bodyobjectThe transformed response body to return from the proxy
headersobjectThe 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.