Concepts

CipherStash Secrets is organized around four core resources: workspaces, environments, clients, and API keys. Understanding how they relate helps you design a secure secrets management strategy.

Workspaces

A workspace is the top-level organizational unit. Each workspace gets its own isolated vault for storing encrypted secrets.

• Separate resources by project or team.
• Each workspace has a unique Cloud Resource Name (CRN) and region (e.g., us-east-1, eu-west-1).
• Secrets stored in one workspace are completely isolated from other workspaces.

Environments

Environments provide cryptographic isolation within a workspace. Each environment maps to its own Key Set in ZeroKMS, so secrets in one environment cannot be decrypted with keys from another. This is the same Key Set primitive used for multi-tenant encryption in the Encryption SDK.

Typical setups include:

When you initialize the SDK, the environment parameter determines which keyset is used:

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

const secrets = new Secrets({
  workspaceCRN: process.env.CS_WORKSPACE_CRN!,
  clientId: process.env.CS_CLIENT_ID!,
  clientKey: process.env.CS_CLIENT_KEY!,
  apiKey: process.env.CS_CLIENT_ACCESS_KEY!,
  environment: "production",
})

Clients

Clients (also called applications) represent the services that need access to secrets. Each client receives a unique client key used for authentication with ZeroKMS.

• A client is associated with one or more environments.
• The CS_CLIENT_ID and CS_CLIENT_KEY environment variables identify and authenticate a client.
• Client keys are shown only once at creation — store them securely.

API keys

API keys (also called access keys) authenticate requests to the CipherStash API. They are separate from client keys and control API-level access.

• Set the CS_CLIENT_ACCESS_KEY environment variable with your API key.
• Roles control permission scope: admin for full access, member for limited access.
• Like client keys, API keys are shown only once at creation.

Credential summary

Security model

• End-to-end encryption — Values are encrypted locally by the SDK before transmission. CipherStash never sees plaintext.
• Workspace isolation — Each workspace has its own vault. No cross-workspace access is possible.
• Environment isolation — Each environment uses a separate Key Set. A secret encrypted in staging cannot be decrypted with production keys. This is the same primitive used for multi-tenant encryption.
• Zero-trust — Every request is authenticated and authorized. There is no implicit trust between services.