Keysets

Keysets are used, in combination with ZeroKMS key material, to derive unique data keys per record. Each keyset maintains its own set of data encryption keys, so data encrypted under one keyset cannot be decrypted with another.

Key Sets are the foundational primitive that powers multi-tenant encryption in the Encryption SDK and environment isolation in Secrets.

Default keyset

Each workspace has a default keyset, which is used to derive data keys for all records in the workspace and meets the needs for most use cases. The default keyset is created automatically when you create a workspace. You can create additional keysets to meet your specific needs.

Create a client with a keyset

By ID

import { Encryption } from "@cipherstash/stack"
import { users } from "./schema"

const client = await Encryption({
  schemas: [users],
  config: {
    keyset: { id: "123e4567-e89b-12d3-a456-426614174000" },
  },
})

By name

const client = await Encryption({
  schemas: [users],
  config: {
    keyset: { name: "Company A" },
  },
})

In Secrets (via environments)

Secrets environments map directly to Key Sets. When you specify an environment, the Secrets SDK automatically uses the corresponding Key Set for encryption and decryption. See Secrets concepts for more detail.

import { Secrets } from "@cipherstash/stack/secrets"

const secrets = new Secrets({
  // ...credentials
  environment: "production", // maps to a Key Set
})

How it works

When you specify a keyset, ZeroKMS derives all data encryption keys from that keyset's root key. This means:

• Data encrypted under keyset A cannot be decrypted with keyset B.
• You can rotate or revoke keys at the keyset level.
• Each tenant's data is cryptographically isolated from every other tenant.

Use cases

• Multi-tenant SaaS — Give each customer their own keyset so their data is cryptographically separated. See Encryption configuration.
• Environment isolation — Use different keysets for production, staging, and development. See Secrets concepts.
• Compliance boundaries — Isolate data by jurisdiction or regulatory requirement.
• Custom isolation boundaries — Key Sets are a general-purpose primitive. Use them for any cryptographic boundary your application needs — per-region, per-department, or per-feature.

Keysets and clients

Keysets can be associated with any number of clients to grant that client access to performing encryption and decryption operations on the data in that keyset.

Granting access to a client

When creating a new keyset, you must choose which clients will be granted access to the keyset. You can manage this by clicking Manage on a particular keyset in the Keysets page of the CipherStash Dashboard.

Revoking access to a keyset

At any time, you can revoke access to a client by removing the association with the keysets which will prohibit that client from accessing the encrypted data in those keysets. You can manage this by clicking Manage on a particular client in the Clients page of the CipherStash Dashboard.

Managing keysets

Via the Dashboard

In the CipherStash Dashboard, you can create a keyset by clicking the Create Keyset button in the Keysets page.

Via the API

To create a keyset via the API, follow these steps:

Step 1: Create an access key

First, create an access key in the CipherStash Dashboard with the role of "Control".

Step 2: Get a service token

Use your access key to get a service token:

curl https://ap-southeast-2.aws.auth.viturhosted.net/api/authorize \
  -H "Content-Type: application/json" \
  -d '{"accessKey": "your_access_key_set_with_control_role"}'

This will return a JSON response containing the access token and expiry information:

{
  "accessToken": "token_value",
  "expiry": 1757529498
}

Step 3: Export the token

Export the access token as an environment variable:

export CTS_TOKEN="the_accessToken_from_previous_step"

Step 4: Create the keyset

Create a keyset using the service token (make sure your workspace is in ap-southeast-2 or update your endpoint):

curl https://ap-southeast-2.aws.viturhosted.net/create-keyset \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CTS_TOKEN" \
  -d '{"name":"my_automated_keyset","description":"automated"}' -v

This will return a JSON response containing the ID of the keyset created:

{
  "id": "key_set_id",
  "name": "my_key_set_name",
  "description": "my_key_set_description"
}

Step 5: Grant access to a client

Grant access to a client by granting access to the keyset. You can find your client ID in the CipherStash Dashboard on the Clients page for your workspace.

curl https://ap-southeast-2.aws.viturhosted.net/grant-keyset \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CTS_TOKEN" \
  -d '{"keyset_id":"key_set_id","client_id":"client_id_to_grant_access_to"}' -v

This will return an HTTP 200 response if successful.