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 one profile and extension instance: the published instance or one workspace dev overlay.

Declare the names

List required names in the manifest. CompozyOS 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 decide per-profile enablement. 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

Use the root profile selector to set a profile-specific value:

compozy --profile marketing 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 published instance. Resolution checks (profile, workspace), then (profile, published), then (shared, workspace), then (shared, published), so a profile binding always outranks a shared one.

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/env/PAGER_TOKEN

Published refs use vault:extensions/global/...; workspace refs use vault:extensions/ws/<workspace>/.... Profile-specific managed refs add profiles/<profile-id>/ beneath that instance prefix. CompozyOS rejects a missing ref, a namespace mismatch, or a ref owned by another profile or instance.

Bind a remote MCP header

For a remote MCP server declared by the extension, bind the same write-only value to one request header:

compozy extension secrets bind incident-review \
  --env PAGER_TOKEN \
  --vault-ref vault:extensions/global/incident-review/env/PAGER_TOKEN \
  --remote-header deployment-api:Authorization

The server must exist in resources.mcp_servers, use the native http transport, and accept the named header under the remote-header policy. For Agent Plugins packages, a type: "streamable-http" server is normalized to that transport during ingestion. Sensitive header values declared in a portable package are skipped; this operator binding is the credential path.

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 declared names, bound names, stale status, and optional remote server/header names. They never contain Vault refs or secret values. 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

Bind a remote MCP header

Inspect presence and remove bindings

Related

On this page