Secret management

With secret management, you can keep sensitive values, such as API keys, passwords, and tokens, out of your process models, job variables, and configuration files. Instead of writing a value into a model, you reference a secret by name, and Camunda resolves that reference to its value at runtime. The value is supplied only where it is needed, so it is never stored in the process itself.

This page is the entry point for how secrets work across Camunda 8. It explains how to reference a secret, where secret values are stored in each offering, how references are resolved, and how access to secrets is controlled. For precise definitions of every term used here, see the secret referenceSecret referenceA placeholder written into a process model that stands in for a secret value, used in a connector field, an input mapping, or a cluster variable. Camunda resolves a secret reference to its value at runtime instead of storing the value in the process itself. glossary entries.

Reference a secret

You reference a secret with a secret referenceSecret referenceA placeholder written into a process model that stands in for a secret value, used in a connector field, an input mapping, or a cluster variable. Camunda resolves a secret reference to its value at runtime instead of storing the value in the process itself.: a placeholder written into a model that stands in for a secret value. The recommended syntax is camunda.secrets.<name>, resolved centrally by the Orchestration ClusterOrchestration ClusterThe Orchestration Cluster is the core component of Camunda 8, powering the automation and orchestration of processes. An Orchestration Cluster includes:. See Using camunda.secrets.* references, and Store and create secrets for how the backing store is configured in each offering.

Syntax	Resolved by	Where you use it	Learn more
camunda.secrets.<name>	The Orchestration ClusterOrchestration ClusterThe Orchestration Cluster is the core component of Camunda 8, powering the automation and orchestration of processes. An Orchestration Cluster includes:	Input mapping FEEL expressions, and connector or credential fields backed by a SECRET_REFERENCE cluster variable	Secret resolution, Secret reference (Orchestration Cluster)Secret reference (Orchestration Cluster)The camunda.secrets. syntax used to reference a secret, written directly in an input mapping or embedded in the value of a cluster variable that an input mapping reads. Unlike a legacy secret reference, the Orchestration Cluster itself resolves this reference through secret resolution, rather than the connector runtime resolving it at execution time.

An older {{secrets.<name>}} syntax, resolved by the connector runtime, remains supported for existing connector models. See Legacy connector secrets.

For a working example of referencing camunda.secrets.<name> in a model, including the FEEL expression rules, see Secret references in input mappings.

Store and create secrets

A reference only resolves to a value once that value is available to the resolving component. How you create and store a secret depends on how you run Camunda 8:

• SaaS: the secret store is provisioned and managed for you. Create and update secret values on a cluster's Cluster secrets tab, then reference them as camunda.secrets.<name>. See Manage connector secrets and the SaaS-managed secretSaaS-managed secretA secret whose value is stored and managed for a SaaS Orchestration Cluster, independent of any individual process. Create, update, and delete a SaaS-managed secret in Camunda Hub, in the left navigation under Clusters, currently under the Cluster secrets tab of a cluster. glossary entry.
• Self-Managed: an operator supplies secret values by configuring a secret store (File, AWS Secrets Manager, or GCP Secret Manager). See secrets configuration. When deploying with the Helm chart, a Kubernetes SecretKubernetes SecretA Kubernetes object that stores small amounts of sensitive data, such as passwords or tokens, separately from Pod specifications and container images. The Camunda Helm chart uses Kubernetes Secrets to supply credentials to Camunda's own components at deployment time. can back the configured store, for example as mounted files for a File store. See Helm charts secret management.
• Local development: no store configuration needed; you manage secrets via c8ctl or c8run and reference them via camunda.secrets.<name>:
  • Manage secrets via c8ctl through the c8ctl cluster secrets CLI, forwarding to the local development cluster — see Manage secrets with c8ctl.
  • Manage secrets via c8run directly through the c8run secrets CLI. See Manage secrets via c8run.

Resolve, list, and troubleshoot

• Secret resolution covers the reference syntax, the two resolution paths, tenant scope, and caching.
• Secret resolution and job activation covers the broker path: the scheduler, caching, and delivery to job workers.
• Troubleshoot secret resolution failures covers the incidents raised when a reference or its injection fails.
• Secrets covers the POST /v2/secrets/resolve and POST /v2/secrets/list API endpoints, and Secrets covers the equivalent Java client commands.

Control access to secrets

The SECRET resource's READ and REVEAL permissions govern who can list and reveal a secret through the /v2/secrets API; they don't govern the broker resolving a reference for job activation. See Authorizations and Secret authorizations don't cover broker-side resolution.

Legacy connector secrets

The legacy secret reference syntax, {{secrets.<name>}}, is resolved by the connector runtimeConnector runtimeThe connector runtime is the execution environment responsible for running connector logic, resolving authentication, resolving secret references, and communicating with external systems. In SaaS, the runtime is fully managed. In Self-Managed environments, the runtime can run inside the cluster or in hybrid mode. itself, at execution time, and can be used in any connector field in the properties panel. The syntax remains fully supported for existing connector models: "legacy" describes its age relative to camunda.secrets.<name>, not its support status. See Using secrets for how to reference a legacy secret in a model, and the Secret reference (legacy)Secret reference (legacy)The {{secrets.}} syntax used in a connector field to reference a secret. The connector runtime resolves the placeholder at execution time, replacing it with the referenced secret's value. glossary entry.

In Self-Managed, a connector secret provider supplies the values behind legacy references, for example from prefixed environment variables or a custom provider. When deploying with the Helm chart, a Kubernetes SecretKubernetes SecretA Kubernetes object that stores small amounts of sensitive data, such as passwords or tokens, separately from Pod specifications and container images. The Camunda Helm chart uses Kubernetes Secrets to supply credentials to Camunda's own components at deployment time. can deliver these values as mounted environment variables. See Connector secrets in Self-Managed and Helm charts secret management.

Compared to camunda.secrets.<name>, the legacy syntax has these limitations:

• No field-scoped resolution: a legacy reference can resolve outside the field it was written in. The secret filter introduced with security notice 61 mitigates this; camunda.secrets.<name> scopes resolution to the field instead. See secret resolution.
• No resource-based authorization: legacy secrets have no SECRET resource permissions and rely on the secret filter instead. See Control access to secrets.
• No external secret store integration: values come from connector secret providers, not from a File, AWS Secrets Manager, or GCP Secret Manager store. See secrets configuration for the stores camunda.secrets.<name> supports.

camunda.secrets.<name> values live in the Orchestration Cluster's configured secret store — not in a connector-attached provider.

Migrating from the legacy syntax?

In Self-Managed, set up the secret store and move your values there first. Then follow Migrate to camunda.secrets.<name>, which covers the step-by-step process, including the connector runtime's fallback mode for incremental migration.

Related resources

• Secret referenceSecret referenceA placeholder written into a process model that stands in for a secret value, used in a connector field, an input mapping, or a cluster variable. Camunda resolves a secret reference to its value at runtime instead of storing the value in the process itself. and its related glossary entries define every term used on this page.

camunda.secrets.<name> (recommended):

• Secret references in input mappings covers referencing camunda.secrets.<name> in a model, with examples.
• Cluster secrets covers referencing SaaS-managed secrets as camunda.secrets.<name>.
• Secrets configuration covers configuring the secret store in Self-Managed.
• Migrate to camunda.secrets.<name> covers moving from the legacy syntax, including the connector runtime's fallback mode.

{{secrets.<name>}} (legacy):

• Using secrets covers referencing secrets from connector fields.
• Cluster secrets covers creating and managing secret values in SaaS.
• Connector secrets in Self-Managed covers configuring connector secret providers.