For the complete documentation index, see llms.txt.
Skip to main content
Version: 8.10 (unreleased)

Secret resolution

Learn about secret resolution references, resolution paths, and where resolution is scoped and cached.

About​

Secret resolution replaces a camunda.secrets.<name> reference, known as a secret reference (Orchestration Cluster), with the value a configured secret store holds for it, without that value being written into a process model, a job variable literal, or a configuration file.

  • This is a separate mechanism from the connector runtime's {{secrets.<name>}} syntax, now named "Secret reference (legacy)".
  • By default, the two forms are resolved independently by different components, and each reads only its own store or providers.
  • Optionally, if the connector runtime is configured for it (camunda.connector.secret-resolver.legacy.mode set to FALLBACK), a legacy reference the runtime cannot find in its providers falls back to the camunda.secrets.<name> store. See Using camunda.secrets.* references.
note

The legacy form was the subject of security notice 61, where an unscoped reference could resolve outside the field it was written in. The secret filter that notice introduces applies only to the legacy form. camunda.secrets.<name> resolution isn't affected: the broker records each reference's position in the job variables and replaces only that position, so a reference can't resolve at a field where it wasn't written.

tip

Desktop Modeler and Camunda Hub flag legacy secret usage when the diagram's selected engine supports camunda.secrets.<name>. Use that hint to guide your migration to the new syntax.

Availability​

Secret resolution is available in both SaaS and Self-Managed.

  • See availability for what each offering provides and what you configure.
  • For an overview of how secrets work in Camunda, including where values are stored and created, see secrets.

Reference syntax​

A reference has the form camunda.secrets.<name>, where <name> is a single, non-empty token of ASCII letters, digits, _, and -.

camunda.secrets.<name> is authored as a FEEL expression (=camunda.secrets.<name>), so a dashed name has to be backtick-escaped. A bare dash is FEEL's minus operator:

=camunda.secrets.`db-password`

An unescaped dashed name is not a reference. FEEL reads =camunda.secrets.db-password as the reference db minus the variable password.

Charset differs by surface​

The engine detects a reference by parsing the FEEL abstract syntax tree, not by matching characters against a fixed set. A name written in a model can therefore be anything a FEEL identifier allows, including unicode letters, $, and any name that is backtick-escaped, such as =camunda.secrets.`tls.crt`.

The gateway API is stricter. POST /v2/secrets/resolve and POST /v2/secrets/list both reject any name outside [\p{Alnum}_-]+.

NameResolves in a modelUsable with /v2/secrets/resolve or /v2/secrets/list
API_TOKENYesYes
`db-password` (backtick-escaped)YesYes (as db-password)
`tls.crt` (backtick-escaped)YesNo: contains a .
`résumé` (backtick-escaped, unicode)YesNo: outside [\p{Alnum}_-]+

A name a model can reference is not guaranteed to be creatable or manageable through the API. Use the API's charset for any name you intend to create, list, or grant permissions on through /v2/secrets/*.

Resolution paths​

There are two resolution paths:

Broker pathGateway API path
Used byJob workers, outbound connectorsInbound connectors (POST /v2/secrets/resolve), Camunda Hub (POST /v2/secrets/list)
WhenAsynchronously, ahead of job activationOn demand, per request
DeliveryLong polling and job pushThe HTTP response

Broker path​

The broker path resolves references in a job's variables in the background and injects the resolved values only when the job is activated. See secret resolution and job activation for the scheduler, caching, and delivery mechanics, including why no resolved value reaches a record, runtime state, or log on this path.

Gateway API path​

The gateway API path serves callers that have no job to wait on.

  • An inbound connector resolves the references an expression evaluation used, in batches, through POST /v2/secrets/resolve.
  • Camunda Hub calls POST /v2/secrets/list to offer known reference names in a credential's secret fields.

Both endpoints share a request and response contract described in secrets. For the full request and response schema of each, see resolve secrets and list secrets.

Physical tenant scope​

A reference names no store, so it always addresses the physical tenant's default secret store: camunda.secrets.X means camunda.secrets.default.X.

Each physical tenant supports exactly one secret store, counted across every store type combined, and that store's ID must be default. Configuring a second store under a different ID is rejected at startup.

Resolving and listing both read the secret stores of the caller's physical tenant only, never another tenant's stores. See validation and constraints for how the one-store-per-tenant rule is validated, and secrets for store configuration.

Cache behavior​

Resolving is cache-first on both paths: the broker's background scheduler and the gateway's resolve endpoint each serve a reference from the store's cache when the cache already holds it, and only read the backing store for a reference the cache doesn't hold yet.

Listing is different by design. What a store's cache holds is the values it has resolved so far, not the tenant's full set of secrets. /v2/secrets/list always reads the configured stores directly rather than serving from the cache.

Unsupported features​

The following features are not currently supported:

Unsupported featureDetails
More than one secret store per physical tenantA reference always addresses the default store.
Pinning a secret to a non-current versionAWS Secrets Manager secrets cannot be pinned to a version stage other than AWSCURRENT, and GCP Secret Manager secrets cannot be pinned to a version other than latest.
Filtering or paginating a POST /v2/secrets/list responseSee secrets.