Getting started with Secrets

Install

Secrets is included in @cipherstash/stack:

npm install @cipherstash/stack

Prerequisites

You need a CipherStash account and workspace credentials. Sign up at cipherstash.com/signup to get started.

Set up your workspace

Before using Secrets, create the following resources in the CipherStash dashboard:

Create a workspace

A workspace is the top-level container for all your resources. Each workspace gets its own isolated vault for storing secrets.

Navigate to the dashboard and create a new workspace, selecting a region (e.g., us-east-1, eu-west-1).

Create an environment

Environments provide cryptographic isolation between stages like production, staging, and development. Each environment uses its own encryption keyset.

Navigate to your workspace's environments page and create a new environment (e.g., "production").

Create a client application

Clients represent the services that access your secrets. Each client receives a unique client key for authentication.

Navigate to your workspace's applications page, create a new client, and select the environment it should access.

Important: Save the client key displayed after creation. It is only shown once.

Create an API key

API keys authenticate requests to the CipherStash API.

Navigate to your workspace's API keys page and create a new key with the appropriate role (admin or member).

Important: Save the API key displayed after creation. It is only shown once.

Configure environment variables

Set the following environment variables with the credentials from the steps above:

CS_WORKSPACE_CRN=your-workspace-crn
CS_CLIENT_ID=your-client-id
CS_CLIENT_KEY=your-client-key
CS_CLIENT_ACCESS_KEY=your-access-key

Store a secret

secrets.ts

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",
})

await secrets.set("DATABASE_URL", "postgres://user:pass@host:5432/db")

The value is encrypted locally before being sent to the CipherStash API. Your plaintext secret never leaves your application.

Retrieve a secret

secrets.ts

const result = await secrets.get("DATABASE_URL")

if (!result.failure) {
  console.log(result.data) // "postgres://user:pass@host:5432/db"
}

The encrypted value is fetched from the API and decrypted locally.

Using the CLI

You can also manage secrets from the terminal without writing code:

npx stash secrets set --name DATABASE_URL --value "postgres://..." --environment production
npx stash secrets get --name DATABASE_URL --environment production

See the CLI reference for all available commands.

Next steps

Learn about core concepts like workspaces and environments
See the full SDK reference for all operations
Use the CLI reference for terminal-based management

Getting started

On this page