Secrets

A secret is a named value in an environment, such as an API key or a database URL. Values are encrypted, and every change is tracked so you can roll back.

Apps receive secret values through the CLI, SDKs, and sync. Coding agents do not: an agent profile gives them placeholders, and Stashbase injects the value only for approved requests. To show an agent what an environment contains, export a value-free schema.

Format

Each secret has a name, a value, and an optional comment.

• Name: uppercase letters, digits, and underscores, 2–255 characters, not starting with a digit. The dashboard formats names as you type.
• Value: any string up to 16 KB (UTF-8).

Here are some examples of valid and invalid secret names:

• Invalid: db_password
• Invalid: DATABASE-URL
• Valid: DB_PASSWORD
• Valid: DATABASE_URL

References

Stashbase also supports secrets referencing so you can easily refer to other secrets in the same environment. You can reference secrets using the following surrounding characters (just like in dotenv files) ${NAME}.

A secret cannot reference itself. The dashboard and the CLI warn you about references that are malformed or point to a secret that does not exist. Our SDKs and CLI support expanding those references to their values or returning the secrets as plain text.

Example

Here is an example of referencing another secrets:

DB_PORT=5432
DB_USER=admin
DB_NAME=postgres
DB_HOST=localhost
DB_PASSWORD=mypassword
DB_URL=postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME}

Multiline secrets

Stashbase supports multiline secrets by default. Using the web dashboard you can easily create multiline secrets with the Enter key when editing the values. Backslashes that are part of the secret value are escaped automatically as well \\ in the dotenv format.

Dotenv format

When you are editing secrets in the dotenv format (with CLI or using web dashboard), multiline secrets must begin with double quotes and end with double quotes. Double quotes inside a multiline secret that are not at the end of a line are automatically escaped as \".

If you add double quotes at the end of the line, it marks the end of the multiline secret so if you want to preserve them as part of the secret, you need to escape them as well \".

With Stashbase libraries you can use multiline string literals or use new line character \n to create new lines. Check out example of how to use multiline secrets with CLI.

Examples

Here are some examples of multiline secrets in the dotenv format:

SSL_CERTIFICATE="-----BEGIN CERTIFICATE-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7wvZdf8Y1X+7fHtCxFNh
FsG7DbcCeG6fRro3D9EDQ2WxNs2t6HvOkfFrrqaX52zj3OtGVxFfOd2ZhZ9t7sf+
5l5kgOZHqIbVltEj9HkR9rkNSvud8VfMyV29M8WqF+88oPaoyxKjXExsxtTKnMKX
-----END CERTIFICATE-----"

PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
6HvOkfFrrqaX52zj3OtGVxFfOd2ZhZ9t7sf+5l5kgOZHqIbVltEj9HkR9rkNSvu
d8VfMyV29M8WqF+88oPaoyxKjXExsxtTKnMKXYTO2xtJHyFj69zRU1leHSlD0OH
...
-----END PRIVATE KEY-----"

YAML format

With Stashbase CLI you can also use the YAML format to output/read secrets including multiline ones. To do that, you use the pipe symbol | to mark that the secret is multiline followed by the indented secret value.

If there are any double quotes inside those multiline secrets they will be automatically escaped as \", including the ones at the end of the line.

Examples

Here are some examples of multiline secrets in the YAML format:

SSL_CERTIFICATE: |
  -----BEGIN CERTIFICATE-----
  MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7wvZdf8Y1X+7fHtCxFNh
  FsG7DbcCeG6fRro3D9EDQ2WxNs2t6HvOkfFrrqaX52zj3OtGVxFfOd2ZhZ9t7sf+
  5l5kgOZHqIbVltEj9HkR9rkNSvud8VfMyV29M8WqF+88oPaoyxKjXExsxtTKnMKX
  -----END CERTIFICATE-----

PRIVATE_KEY: |
  -----BEGIN PRIVATE KEY-----
  6HvOkfFrrqaX52zj3OtGVxFfOd2ZhZ9t7sf+5l5kgOZHqIbVltEj9HkR9rkNSvu
  d8VfMyV29M8WqF+88oPaoyxKjXExsxtTKnMKXYTO2xtJHyFj69zRU1leHSlD0OH
  -----END PRIVATE KEY-----

Comments

Each secret can have an optional comment associated with it. The comment can be referred to as a comment in plain text files (dotenv, YAML). Comments can be single line or multiline.

Comments are formatted in the way that empty lines at the beginning and at the end are automatically removed but preserved if they are inside the comment. All trailing whitespace is also automatically removed for each line. Leading whitespaces are preserved.

Changes (history)

All secret changes are tracked and persisted in the changelog for each environment. To see the changes for a single secret:

• Go to the Secrets tab
• Click the history option for any specific secret
• View and manage changes for that particular secret

Security