Extension Secret Bindings

This page helps you provide credentials to an extension without putting plaintext in its manifest, command history, logs, or API responses. A binding connects one declared environment name to a Vault reference for exactly one extension instance: the global published instance or one workspace dev overlay.

Declare the names

List required names in the manifest. Compozy reports names through requires_env, missing_env, and bound_env_keys; it never returns the values.

[extension]
name = "incident-review"
version = "1.0.0"
min_compozy_version = "0.3.0-beta.1"
requires_env = ["PAGER_TOKEN", "REGION"]

Bindings do not make install active and missing values do not block enable. They affect subprocess launch only when the current manifest still declares the name.

Set a value from hidden input

For an interactive terminal, omit --value-stdin and enter the value at the hidden prompt:

compozy extension secrets set incident-review --env PAGER_TOKEN

For automation, send the value on stdin. Never place it in argv:

printf '%s' "$PAGER_TOKEN" | \
  compozy extension secrets set incident-review --env PAGER_TOKEN --value-stdin -o json

Use --workspace <workspace> to target a workspace dev overlay. Without it, the command targets the global published instance.

Bind an existing Vault ref

An existing reference must use the extension Vault namespace and match the target instance:

compozy extension secrets bind incident-review \
  --env PAGER_TOKEN \
  --vault-ref vault:extensions/global/incident-review/PAGER_TOKEN

Global refs use vault:extensions/global/...; workspace refs use vault:extensions/ws/<workspace>/.... Compozy rejects a missing ref, a namespace mismatch, or a ref owned by another instance.

Inspect presence and remove bindings

compozy extension secrets list incident-review -o json
compozy extension secrets unset incident-review --env PAGER_TOKEN -o json

List responses contain names, refs, and presence metadata only. Unset removes the binding and deletes an unreferenced managed extension_env Vault value; it does not delete a shared or differently owned ref.

Bindings survive updates under the same managed identity. When an update removes a name from requires_env, the stale binding remains visible for cleanup but is not injected into the process.

Declare the names

Set a value from hidden input

Bind an existing Vault ref

Inspect presence and remove bindings

Related

On this page