CipherStash Documentation


Device Code authentication

When running CipherStash QX interactively, most likely when you are doing local development, you can authenticate with CipherStash QX using device code authentication.

To connect to CipherStash QX and authenticate, use Stash.connect().

import { Stash } from "@cipherstash/stashjs";

const stash = await Stash.connect();

Pass a profileName option to load a specific profile from ~/.cipherstash.

For example

import { Stash } from "@cipherstash/stashjs";

const stash = await Stash.connect({ profileName: "dev-local" });

Or instead of stating the profile name to load everytime, you can set a profile name in an environment variable CS_PROFILE_NAME.

Stash.connect() will always load that profile.

If you don’t specify a profile name option, or have an environment profile set, Stash.connect() will load the profile in this folder ~/.cipherstash/default.

When Stash.connect() is run, you will be redirected to your browser to log in.

Once you have completed the log in steps you will now be able to use the stash client.

Machine-to-machine authentication

To connect to CipherStash QX programmatically (i.e in Production or CI), you will need to use a CipherStash QX access key.

To generate an access key follow the instructions here.

Then set the below environment variables.

Ensure that these are the only environment variables set for CipherStash QX. You will find these environment variable values in the profile you created the access key for, in this location ~/.cipherstash/<profile>/profile-config.json.

You can read more about these configuration options here

  • CS_SERVICE_FQDN: This is the fqdn (fully qualified domain name) of the CipherStash QX service in which this workspace exists.

    The default is To check what fqdn your workspace exists in, you can check your profile set in ~/.cipherstash/<profile>/profile-config.json,

  • CS_WORKSPACE: The id of the workspace the access key is for.

  • CS_IDP_CLIENT_SECRET: The CipherStash QX access key you created.

  • CS_KMS_KEY_ARN: Set in ~/.cipherstash/<profile>/profile-config.json, keyManagement.key.arn.

  • CS_NAMING_KEY: Set in ~/.cipherstash/<profile>/profile-config.json, keyManagement.key.namingKey.

  • CS_KMS_KEY_REGION: Set in ~/.cipherstash/<profile>/profile-config.json, keyManagement.key.region.

For CipherStash QX managed KMS keys add the below:

  • CS_AWS_REGION: Set in ~/.cipherstash/<profile>/profile-config.json, keyManagement.awsCredentials.region.

  • CS_KMS_FEDERATION_ROLE_ARN: Set in ~/.cipherstash/<profile>/profile-config.json, keyManagement.awsCredentials.roleArn

If you are managing your own KMS keys add these environment variables:

  • CS_AWS_ACCESS_KEY_ID: Set in ~/.cipherstash/<profile>/profile-config.json, keyManagement.awsCredentials.accessKeyId

  • CS_AWS_SECRET_ACCESS_KEY: Set in ~/.cipherstash/<profile>/profile-config.json, keyManagement.awsCredentials.secretAccessKey

Load profile using environment variables

To authenticate using these environment variables use Stash.loadProfileFromEnv(). This will create a stash profile to pass to Stash.connect()

import { Stash } from "@cipherstash/stashjs";

const profile = Stash.loadProfileFromEnv();

const stash = await Stash.connect(profile);