Secrets and Variables

Manage the secrets and variables a deployment file refers to with from_secret and from_variable.

client.secrets and client.variables manage the values your apps read at runtime: a deployment file refers to them with from_secret and from_variable. The Secrets guide explains how they reach an app. This page covers managing them from code.

The two resources differ in one way that shapes the whole API: a variable's value is returned on every read, and a secret's is returned exactly once, by the call that sets it. Anything worth hiding belongs in secrets.

	Read	Write
Secrets	`secrets:read`	`secrets:write`
Variables	`variables:read`	`variables:write`

Secrets

const { data: secret } = await client.secrets.create({
  name: "DB_PASSWORD",
  value: process.env.DB_PASSWORD!,
  environment: "production",
});
secret.maskedValue; // "hu••••r2", safe to log or display

const { data: secrets } = await client.secrets.list({ environment: "production" });
// name, environment, version, who changed it and when — never the value

create and update return the plaintext once, in value. Nothing returns it afterwards — list and get describe a secret without it, and no endpoint decrypts one. A lost value is replaced, not recovered.

Method	Description
`list(...)`	Every secret, or those in one `environment`, without values.
`get(secretId)`	One secret, without its value.
`create(...)`	Stores a secret. Takes `name`, `value`, and optionally `description` and `environment`.
`update(secretId, ...)`	Replaces the value, optionally with a new `description`, and bumps `version`.
`delete(secretId)`	Removes it.
`usage()`	How many secrets the project holds, and how many it may hold.
`audit(secretId)`	Who changed it and when — never to what.

environment is one of default, development, staging or production, and defaults to default.

Variables

await client.variables.create({ name: "LOG_LEVEL", value: "debug", environment: "staging" });

const { data: variables } = await client.variables.list();
variables[0].value; // "debug" — returned in full on every read

Variables have the same list, get, create and delete methods as secrets. Their update takes a new value, a new description, or both, and there is no usage or audit.

Before you debug

Two API behaviours look like bugs until you know them:

Writes need an owner or admin. The API checks the role of the person who created the key, separately from the key's scopes. A key belonging to a plain member is refused with 403 even when it carries secrets:write.
Creating secrets is rate-limited to 100 per project every 10 minutes, shared by every key and machine working on the project. A project that has reached its secret limit answers 402 — see Usage Limits.

In CI, cosmoner secrets set reads the value from a pipe, so it never appears in a command line or a log.

Secrets

Variables

Before you debug

On this page