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

Migrate to `camunda.secrets.<name>`

camunda.secrets.<name> is the recommended secret reference syntax, resolved centrally by the Orchestration Cluster rather than by the connector runtime. This page explains how to rewrite existing {{secrets.<name>}} references in your connector models, and which extra steps apply if you run your own connector runtime.

note

The legacy {{secrets.<name>}} syntax remains fully supported, so you can migrate at your own pace.

Why migrate​

Resolving secrets centrally in the Orchestration Cluster gives you capabilities the connector runtime's own resolution doesn't have:

  • Field-scoped resolution: a reference only resolves at the field where it was written. See secret resolution and security notice 61 for the legacy behavior this replaces.
  • External secret store support: in Self-Managed, values come from a File, AWS Secrets Manager, or GCP Secret Manager store instead of environment-variable-based connector secret providers. See secrets configuration.
  • Resource-based access control: the SECRET resource's READ and REVEAL authorizations govern who can list and reveal secrets through the API. See Control access to secrets.
  • Resolution kept off the connector runtime path: references resolve ahead of job activation, so a value never lands in a record, runtime state, or log. See Secret resolution and job activation.

Feature differences​

{{secrets.<name>}} (legacy)camunda.secrets.<name> (recommended)
Resolved byThe connector runtime, at execution timeThe Orchestration Cluster, ahead of job activation or on demand through the API
Where you use itAny connector field in the properties panelConnector fields that take a secret and any input mapping, as a FEEL expression (=camunda.secrets.<name>); Camunda Hub credential fields, without the =
Value sourceConnector secret providers, for example prefixed environment variables or a custom provider; in SaaS, the cluster's managed secretsA File, AWS Secrets Manager, or GCP Secret Manager store in Self-Managed; managed secrets in SaaS
AuthorizationNone; the secret filter restricts which fields may resolve a secretThe SECRET resource's READ and REVEAL authorizations govern the /v2/secrets API; broker-side resolution is not governed by them
Tenant awarenessNot scoped per physical tenant unless you opt in to a tenant-aware provider in the connector runtime configurationEach physical tenant resolves its own configured secret store
CachingValues are read from the provider on each executionCache-first with a configurable cache lifetime, so rotated values become available without a restart

For the full behavior of the recommended syntax, see Secret resolution and Secret resolution and job activation. For the legacy syntax, see Using secrets.

Choose your migration path​

The steps you need depend on which connector runtime runs your connectors.

Your setupWhat you do
SaaS, with the Camunda-hosted connector runtimeUpdate the references in your models. See Migrate in SaaS.
Self-Managed, or SaaS with your own connector runtime (hybrid mode)Move the secret values first, then update your models. See Migrate with your own connector runtime.

Migrate in SaaS​

In SaaS with the Camunda-hosted connector runtime, migrating means updating the references in your models. The secrets on a cluster's Cluster secrets tab already back both syntaxes, so you don't copy values or change any runtime configuration.

  1. Check that each secret your models use exists on the cluster's Cluster secrets tab and follows the secret naming rule.
  2. Replace each {{secrets.NAME}} reference with camunda.secrets.NAME, as shown in Rewrite secret references.
  3. Deploy the updated models to the cluster that holds the secrets.

If you run your own connector runtime against a SaaS cluster, follow Migrate with your own connector runtime instead. In that setup, legacy references resolve from your runtime's own secret providers, not from the Cluster secrets tab.

Migrate with your own connector runtime​

When you operate the connector runtime yourself, legacy references resolve from that runtime's secret providers, so you move the values to the Orchestration Cluster's store before you update your models. This applies to Self-Managed and to a self-managed connector runtime connected to a SaaS cluster.

  1. Prepare the store. In Self-Managed, configure a secret store for the Orchestration Cluster. The connector runtime's secret providers alone are not enough, because camunda.secrets.<name> doesn't read them. In SaaS, the store is the cluster's Cluster secrets tab.
  2. Copy the secret values. Move each secret value from your connector secret provider into the store under the same name. Follow the secret naming rule.
  3. (Optional) Enable fallback mode. Set camunda.connector.secret-resolver.legacy.mode to FALLBACK on the connector runtime, as described in Migrate incrementally with fallback mode. Models you haven't updated yet then keep working while you migrate them.
  4. Update your models. Replace each {{secrets.NAME}} reference with camunda.secrets.NAME, as shown in Rewrite secret references.
  5. Turn off legacy resolution. Once no model contains a {{secrets.<name>}} reference, set camunda.connector.secret-resolver.legacy.mode to OFF and remove the connector secret provider configuration. Any legacy reference you missed then fails with an error naming this setting, instead of resolving from a leftover provider.

Migrate incrementally with fallback mode​

Fallback mode lets models that still use the legacy syntax resolve from the Orchestration Cluster's store, so you don't have to update every model at once. The connector runtime's camunda.connector.secret-resolver.legacy.mode setting controls where legacy references resolve from:

  • ON (default): no fallback. The runtime resolves {{secrets.<name>}} only from its configured secret providers.
  • FALLBACK: when a legacy reference's name isn't found in a configured secret provider, the runtime looks the name up in the same secret store that backs camunda.secrets.<name>.
  • OFF: the runtime doesn't resolve legacy references at all. Use it once your migration is complete.

With FALLBACK set, you can move a secret's value into the Orchestration Cluster's store first and keep existing models on the legacy syntax. Models you haven't touched keep resolving, now from the store, while you update them field by field.

This setting only applies to a connector runtime you operate. In SaaS, the Camunda-hosted connector runtime already resolves legacy references from the Cluster secrets tab.

Rewrite secret references​

A camunda.secrets.<name> reference is a FEEL expression, so the field starts with = and the reference itself is never quoted. Use these forms directly in connector fields in the properties panel and in input mappings.

Use caseLegacy referencecamunda.secrets.<name> reference
The whole field is a secret{{secrets.MY_API_KEY}}=camunda.secrets.MY_API_KEY
Text around the secretBearer {{secrets.MY_API_KEY}}="Bearer " + camunda.secrets.MY_API_KEY
A secret in a FEEL context= { myHeader: "{{secrets.MY_API_KEY}}" }= { myHeader: camunda.secrets.MY_API_KEY }
A secret name with a dash{{secrets.db-password}}=camunda.secrets.`db-password`

Keep the following in mind when you rewrite a reference:

  • Remove the quotes around the reference. A quoted reference, such as ="camunda.secrets.MY_API_KEY", is rejected at deployment.
  • Don't put a reference inside a list, such as =[camunda.secrets.MY_API_KEY]. This is also rejected at deployment. Give each secret its own field or input mapping instead.
  • In a Camunda Hub credential field, enter the reference without a leading =, for example camunda.secrets.MY_API_KEY. See reference a secret from a credential field.

For the full rules, see secret references in input mappings. To reuse the same references across processes, you can also store them in a cluster variable of kind SECRET_REFERENCE. See resolve secret references in a cluster variable.

Name your secrets​

A secret name can contain only ASCII letters, digits, _, and -. Rename any secret with other characters before you migrate. To learn where such a name still works, see reference a name with other characters.

A name with a dash must be backtick-escaped, for example =camunda.secrets.`db-password` . Without the backticks, FEEL reads camunda.secrets.db-password as db minus password.

Testing​

To supply cluster secrets when you test processes with Camunda Process Test, see cluster secrets in Camunda Process Test.