Variables

envless.variables.create()

Create one variable in an environment

ts
create(project: string, environment: string, body: VariableInput, options?: ProductScope): Promise<VariableResource>

Creates a single variable in an environment and resolves the stored row.

value must already be ciphertext from encryptValue. The server holds no key and will not encrypt for you, so a plaintext value is refused with 400 variable.ciphertext_invalid and error.field naming the offender. defaultValue obeys the same rule whenever you send it, and plaintext that reaches it is permanent, since it is copied into every version snapshot taken afterwards and into every rollback made from one.

The ciphertext check runs before the project and environment are resolved, so a malformed value aimed at a project that does not exist returns 400 and not 404. A name already taken by a live variable is 409 variable.name_conflict, and hitting the 1000 variable ceiling is 409 plan.limit_reached rather than a 402.

name must match ^[A-Za-z_][A-Za-z0-9_]*$ and be 1 to 100 characters: letters, digits and underscores only, never starting with a digit. A name that fails either rule is a 400, not a silent fix. Lowercase is legal. Envless stores and returns the name with exactly the casing you send and never upper-cases it for you, but uniqueness inside the environment is judged without regard to case, so creating api_key in an environment that already holds API_KEY is 409 variable.name_conflict rather than a second variable.

Example

ts
const { workspaceId } = await envless.me.get()

const variable = await envless.variables.create('api', 'production', {
    name: 'STRIPE_SECRET_KEY',
    value: await encryptValue('sk_live_51H8xq', passphrase, workspaceId ?? ''),
    required: true
})

console.log(variable.id)

Parameters

ParameterTypeRequiredDescription
projectstringYesProject slug the environment belongs to.
environmentstringYesEnvironment slug to create the variable in.
body.namestringYesVariable name. Matches ^[A-Za-z_][A-Za-z0-9_]*$, 1 to 100 characters, unique among the live variables in the environment without regard to case.
body.valuestringYesCiphertext from encryptValue, 1 to 20000 characters and prefixed v1: or v2:.
body.typestringNoOne of the VARIABLE_TYPE values, defaults to string.
body.isSecretbooleanNoMarks the variable as a secret, which the example feed reports as secret: true. Stored, but not echoed in the response.
body.visibilitystringNoOne of the VARIABLE_VISIBILITY_LEVELS values, defaults to server.
body.requiredbooleanNoMarks the variable as required for the environment, defaults to false.
body.defaultValuestring | nullNoCiphertext fallback encrypted with the same workspace key, or null.
options.productstringNoProduct slug, needed when the project slug is not unique in the workspace.
options.signalAbortSignalNoCancels the request.

Returns

VariableResource for the new variable, including the generated id you need for apply and the id routes.

Worth knowing

  • isSecret is accepted and stored but is not part of the response body.
  • createMany and apply run the same v1:/v2: prefix check, so plaintext is refused on every write route, not only this one.
  • Names are case reserved, not case normalised. Api_Key is stored as Api_Key, and no other casing of it can exist in the same environment.
  • A name is checked locally before anything is sent, so an unusable name never reaches the network.
  • A local refusal rejects the returned promise with an EnvlessApiError carrying request.body_invalid and field: name, the same vocabulary the API uses, but with no requestId because nothing was sent.

Required scopes

variables:write

Underlying endpoint

POST /projects/{slug}/environments/{environmentSlug}/variables

Request and response schema, every error code, and a live playground.

In Python

envless.variables.create()

The same method in envless-sdk, the Python SDK, with the same request, retries and errors.

In Ruby

Envless.variables.create

The same method in envless-sdk, the Ruby gem, with the same request, retries and errors.

In PHP

$envless->variables->create()

The same method in envless/sdk, the PHP SDK, with the same request, retries and errors.