CipherStash Documentation

Best practices using datasets and clients

If you have already stepped through Rails or Sequelize getting started guide, you would have already come across the concepts of datasets and clients.

This reference document will step through best practices when using datasets and clients in CipherStash.


For local development and testing, each developer should sign up and create their own account with CipherStash.

After creating an account the dashboard will display a Workspace ID.

When you sign in, you will receive confirmation on the CLI as to which Workspace you are authenticated with.

Waiting for authentication...
Setting up a default workspace id
Fetching workspaces
    Workspace {
        id: "ABC12345678",
        name: "Vitur Workspace",
Setting default Workspace ID: ABC12345678
Logging in to Vitur Workspace ID: ABC12345678
Login succeeded!

Your workspace is a container which groups together datasets in a particular geographic region.

Create a separate CipherStash account for any shared environments (like production, qa, or staging).


A dataset holds configuration for one or more database tables that contain data to be encrypted.

The configuration includes:

  • The types of indexes set for each column in the table.
  • The mode for each index.
  • The data type.
  • Settings for match indexes, eg tokenization settings.

Create a separate dataset for each environment you are handling sensitive data in.

This allows the dataset configuration to be updated and tested without affecting another environment.

Make sure you specify a clear and unique description when creating the dataset, that identifies what the dataset is used for.

To create a dataset run:

stash datasets create patients --description "Test application - CI"


A client allows an application to programatically access a dataset.

A dataset can have many clients (for example, different applications working with the same data), but a client belongs to exactly one dataset.

To create a client run:

stash clients create --dataset-id $DATASET_ID "Test application - CI"

A client id and key will be returned.

The client key will only ever be displayed at this time.

Make sure to note this down somewhere secure, like a password vault.