Client Encryption Keys

Client Encryption Keys are asymmetric key pairs generated by Basis Theory for encrypting sensitive data on the client side. The public key is used to encrypt data in your frontend (e.g., with Elements), and the encrypted payload can be sent to your backend and then to Basis Theory for secure storage or processing.

Key Expiration: An encrypted payload is only valid for the lifetime of the encryption key. After a key expires, Basis Theory can no longer decrypt payloads that were encrypted with that key.

API Endpoints

Create Key

Create a new key. The public key is only returned when creating a key.

POST

https://api.basistheory.com/keys

Permissions

keys:create

Request

cURL

curl -X POST "https://api.basistheory.com/keys" \
  -H "BT-API-KEY: <MANAGEMENT_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "expires_at": "2026-05-01T00:00:00Z"
  }'

Node

await client.keys.create({
  expires_at: "2026-05-01T00:00:00Z"
});

C#

await client.Keys.CreateAsync(new ClientEncryptionKeyRequest {
  ExpiresAt = DateTimeOffset.Parse("2026-05-01T00:00:00Z")
});

Java

new KeysClient(ClientOptions.builder().build())
  .create(ClientEncryptionKeyRequest.builder()
    .expiresAt(OffsetDateTime.parse("2026-05-01T00:00:00Z"))
    .build());

Python

client.keys.create(expires_at="2026-05-01T00:00:00Z")

Go

key, err := client.Keys.Create(ctx, &basistheory.ClientEncryptionKeyRequest{
  ExpiresAt: timePtr(time.Date(2026, 5, 1, 0, 0, 0, 0, time.UTC)),
})

Request Body

Field	Type	Required	Description
expires_at	string	No	Expiration date (ISO 8601). Defaults to 6 months from creation. Maximum 1 year from creation.

Response

Returns a Key if successful. Returns an error if there were validation errors.

{
  "key_id": "b1e2c3d4-5678-1234-9abc-def012345678",
  "public_key_pem": "-----BEGIN PUBLIC KEY-----\nWQ4geAENWHyR7+g94nN6lFZzY7YdGWxPtlX/16fJ4z0=\n-----END PUBLIC KEY-----",
  "expires_at": "2026-05-01T00:00:00Z"
}

List Keys

List all keys for the current tenant. The public key is not included in the response.

GET

https://api.basistheory.com/keys

Permissions

keys:read

Request

cURL

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

Node

await client.keys.list();

C#

await client.Keys.ListAsync();

Java

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

Python

client.keys.list()

Go

keys, err := client.Keys.List(ctx)

Response

Returns an array of Key.

[
  {
    "key_id": "b1e2c3d4-5678-1234-9abc-def012345678",
    "public_key_pem": "-----BEGIN PUBLIC KEY-----\nWQ4geAENWHyR7+g94nN6lFZzY7YdGWxPtlX/16fJ4z0=\n-----END PUBLIC KEY-----",
    "expires_at": "2026-05-01T00:00:00Z"
  }
]

Get Key by ID

Get a key by ID. The public key is not included in the response.

GET

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

Permissions

keys:read

Request

cURL

curl "https://api.basistheory.com/keys/{id}" \
  -H "BT-API-KEY: <MANAGEMENT_API_KEY>"

Node

await client.keys.get("{id}");

C#

await client.Keys.GetAsync("{id}");

Java

new KeysClient(ClientOptions.builder().build()).get("{id}");

Python

client.keys.get("{id}")

Go

key, err := client.Keys.Get(ctx, "{id}")

Response

Returns a Key. Returns an error if the key does not exist.

{
  "key_id": "b1e2c3d4-5678-1234-9abc-def012345678",
  "public_key_pem": "-----BEGIN PUBLIC KEY-----\nWQ4geAENWHyR7+g94nN6lFZzY7YdGWxPtlX/16fJ4z0=\n-----END PUBLIC KEY-----",
  "expires_at": "2026-05-01T00:00:00Z"
}

Delete Key

Delete a key by ID.

DELETE

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

Permissions

keys:delete

Request

cURL

curl -X DELETE "https://api.basistheory.com/keys/{id}" \
  -H "BT-API-KEY: <MANAGEMENT_API_KEY>"

Node

await client.keys.delete("{id}");

C#

await client.Keys.DeleteAsync("{id}");

Java

new KeysClient(ClientOptions.builder().build()).delete("{id}");

Python

client.keys.delete("{id}")

Go

err := client.Keys.Delete(ctx, "{id}")

Response

Returns no content (204). Returns an error if the key does not exist.

---

Key Object

Attribute	Type	Description
key_id	string	Unique identifier for the key
public_key_pem	string	The public key in PEM format
expires_at	string	When this key expires (ISO 8601)