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.
Permissions
proxy:create
Request
- cURL
- JavaScript
- C#
- Java
- Python
- Go
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
}'
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
});
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
});
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));
}
}
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
))
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.
Permissions
proxy:read
Request
- cURL
- JavaScript
- C#
- Java
- Python
- Go
curl "https://api.basistheory.com/proxies" \
-H "BT-API-KEY: <MANAGEMENT_API_KEY>"
import { BasisTheory } from "@basis-theory/basis-theory-js";
const bt = await new BasisTheory().init("<MANAGEMENT_API_KEY>");
const proxies = await bt.proxies.list();
using BasisTheory.net.Proxies;
var client = new ProxyClient("<MANAGEMENT_API_KEY>");
var proxies = await client.GetAsync();
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);
}
}
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()
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.
Permissions
proxy:read
Request
- cURL
- JavaScript
- C#
- Java
- Python
- Go
curl "https://api.basistheory.com/proxies/5b493235-6917-4307-906a-2cd6f1a90b13" \
-H "BT-API-KEY: <MANAGEMENT_API_KEY>"
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");
using BasisTheory.net.Proxies;
var client = new ProxyClient("<MANAGEMENT_API_KEY>");
var proxy = await client.GetByIdAsync("5b493235-6917-4307-906a-2cd6f1a90b13");
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"));
}
}
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")
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.
Permissions
proxy:update
Request
- cURL
- JavaScript
- C#
- Java
- Python
- Go
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
}'
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
});
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
});
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));
}
}
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
))
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.
Permissions
proxy:update
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
- JavaScript
- C#
- Java
- Python
- Go
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"
}
}'
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",
},
});
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" }
}
});
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")));
}
}
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"
})
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.
Permissions
proxy:delete
Request
- cURL
- JavaScript
- C#
- Java
- Python
- Go
curl "https://api.basistheory.com/proxies/433013a6-a614-4e1e-b2aa-5fba67aa85e6" \
-H "BT-API-KEY: <MANAGEMENT_API_KEY>" \
-X "DELETE"
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");
using BasisTheory.net.Proxies;
var client = new ProxyClient("<MANAGEMENT_API_KEY>");
await client.DeleteAsync("433013a6-a614-4e1e-b2aa-5fba67aa85e6");
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"));
}
}
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")
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.
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.
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"
}'
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. |
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.
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 |
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.