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 (coming soon).

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.

When a developer runs npx stash init, their device-backed client key is automatically granted access to the default keyset. This means no additional configuration is needed for local development.

Create a client key 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 (coming soon)

Secrets environments map directly to keysets. When you specify an environment, the Secrets SDK automatically uses the corresponding keyset for encryption and decryption.

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. Secrets (coming soon) will manage these mappings automatically.
• 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 client keys

Keysets can be associated with any number of client keys to grant each client key access to encryption and decryption operations on data in that keyset.

Granting access to a client key

When creating a new keyset, you must choose which client keys 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 key by removing the association with the keysets. This prohibits that client key from accessing the encrypted data in those keysets. You can manage this by clicking Manage on a particular client key 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"}'

The response contains 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

The response contains the ID of the created keyset:

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

Step 5: Grant access to a client key

Grant access to a client key 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

Returns HTTP 200 on success.