Tokens

Tokens are named text values that can be referenced from environment variables and other generated configuration.

A token can either:

• have a fixed plain value
• use a regular expression to generate a random secret value when the app environment or app service is created or updated

In an app service, token definitions are composed across several levels. Later levels override earlier ones when they use the same token name and the same environment type:

1. service-defined tokens
2. stack-wide tokens
3. stack-service tokens

Tokens with different environment types are separate definitions. When a token is resolved at runtime, an environment-specific token takes precedence over a token without an environment type.

After tokens are materialized on an app service, the app-service token records are the effective runtime values. During a stack upgrade, enabling Override tokens recreates those app-service tokens from the latest service and stack definitions; leaving it disabled keeps the existing app-service token values. Existing generated values are preserved when the latest definition still generates the same token name for the same environment type. This prevents a stack upgrade from rotating database passwords and other generated credentials. Rotate such a credential explicitly when a new value is required.

This page is the public reference for built-in runtime tokens resolved in app-service context.

Some internal or infrastructure-only secret-bearing tokens are intentionally omitted from this public list.

Where tokens are supported

Tokens are commonly supported in:

• environment variable values defined by services, stacks, apps, links, imports, and workloads
• Helm values such as helm.values[].value and other service manifest fields that feed values into a Helm chart
• config contents when configs[].processTokens: true is enabled
• action arguments, database actions, backup actions, and similar generated runtime configuration

Secret tokens in environment variables

Generated tokens are always secret. A fixed-value token is secret when its effective service, stack, stack-service, or app-service definition marks it as secret.

When an environment variable directly references a named token, Wodby automatically carries that classification into the resolved environment variable. The destination becomes secret even when the token is embedded in a larger value, and the complete resolved value is stored in a Kubernetes Secret. The environment-variable definition does not need a duplicate secret flag.

This propagation is intentionally limited to direct named tokens. References under structured namespaces such as links, integrations, database, certs, and keys still require the destination environment variable to be marked secret explicitly. See Environment variables.

app

• app.id: application ID, not app environment ID
• app.name: application machine name
• app.title: application title

instance

instance is the legacy token namespace for an app environment. It remains available for template compatibility.

• instance.id: app environment ID
• instance.name: app environment machine name
• instance.namespace: Kubernetes namespace for the app environment
• instance.title: app environment title

kubernetes

• kubernetes.id: Kubernetes cluster ID
• kubernetes.externalID: cluster external ID
• kubernetes.name: cluster machine name
• kubernetes.fullName: cluster full name

Infrastructure-oriented FRPC tokens are also supported under kubernetes.frpc.*, but the secret-bearing/internal subset is intentionally not documented here.

env

env is the legacy token namespace backed by the internal environment-policy record. Prefer instance for app environment identity and env.type for behavior that depends on an environment type.

• env.id: environment ID
• env.name: environment machine name
• env.title: environment title
• env.type: environment type

org

• org.id: organization ID

service

• service.id: app-service ID
• service.name: app-service machine name
• service.title: app-service title
• service.host: app-service hostname
• service.fqdnPrefix: generated host prefix used for domains
• service.primaryURL: primary URL for the service, including scheme when a primary domain exists
• service.primaryHost: primary domain name for the service
• service.mainPort.number: port number of the primary port on the primary endpoint
• service.mainPort.protocol: protocol of the primary port on the primary endpoint
• service.replicas: app-service replica count
• service.secrets.env: generated Kubernetes Secret name used for secret environment variables

Legacy service.helm.release is still supported for backward compatibility.

helm

• helm.release: resolved Helm release name for the current app service

Use this token when a chart exposes labels, selectors, or values keyed by the Helm release name.

stack

• stack.id: stack ID
• stack.name: stack machine name
• stack.title: stack title
• stack.version: stack version
• stack.rev.id: stack revision ID
• stack.rev.number: stack revision number

database

Available when the current app-service context exposes a database.

• database.host: database hostname. This is private when accessed through an app service with a private database user, otherwise public
• database.port: database connection port. This is private when available, otherwise public
• database.driver: database driver, based on the database kind
• database.root.name: database superuser username
• database.root.password: database superuser password
• database.user.name: database username for the current app-service context
• database.user.password: database user password for the current app-service context
• database.db.name: database name for the current app-service context
• database.db.charset: database charset for the current app-service context
• database.db.collation: database collation for the current app-service context

links

Accessed as links.[name].[token].

• links.[name].host: linked app-service hostname
• links.[name].port: primary port of the linked app service's primary endpoint
• links.[name].service.*: service token from the linked app service. See service
• links.[name].instance.*: app environment token from the linked app service. See instance
• links.[name].env.[env-var-name]: environment-variable value from the linked app service
• links.[name].tokens.[token-name]: token value from the linked app service
• links.[name].database.*: database token from the linked app service. See database

configs

Accessed as configs.[name].[token].

• configs.[name].configMap: generated Kubernetes ConfigMap name for the named config

keys

Available to a service that declares a generated key in its service.yml. Accessed as keys.[name].[field]:

• keys.[name].privateKey: PKCS#8 private-key PEM
• keys.[name].privateKeyBase64: base64-encoded PKCS#8 private-key PEM
• keys.[name].publicKey: PKIX public-key PEM
• keys.[name].publicKeyBase64: base64-encoded PKIX public-key PEM
• keys.[name].fingerprint: unpadded base64url-encoded SHA-256 fingerprint of the PKIX public key

The keys namespace is available only in the owning app-service context and is not exposed under links. Environment variables that use a private-key field must be marked secret: true.

volumes

Accessed as volumes.[name].[token].

• volumes.[name].size: effective volume size in GB
• volumes.[name].claim: generated PVC name for the named volume
• volumes.[name].storageClassName: configured Kubernetes storage class. An unset class resolves as an omitted Helm value so the cluster can apply default storage-class admission.

integrations

Accessed as integrations.[name].[token].

• integrations.[name].key: integration key or secret value
• integrations.[name].variables.[variable-name]: exported integration variable by name