Skip to main content

What are secrets?

Secrets are sensitive values - API keys, database passwords, TLS certificates - that need to be encrypted at rest and tightly access-controlled. In Nexus, secrets are:
  • Encrypted with AES-256-GCM at rest
  • Never returned in plaintext via the audit log
  • Versioned - every write creates a new version; a previous version can be promoted to become the current value
  • Scoped to a service and an environment
  • Only available to backend services (secret keys); frontend services (public keys) never receive secrets

Key names

Secret keys follow the pattern ^[a-zA-Z]([a-zA-Z0-9_.:-]*[a-zA-Z0-9])?$ - letters, digits, dots, underscores, hyphens, and colons. Examples: stripe.secret_key, db:password, TLS_CERT

Secret types

Reading secrets

All backend SDKs provide a typed accessor. Calling GetSecret with a public key or on a frontend-kind service raises an error - secrets are never sent to frontend services.
GetSecret raises ErrPublicKeyRestricted (Go) / NexusPublicKeyError (Node) if called with a public key. It raises ErrServiceKindMismatch / NexusServiceKindMismatchError on a kind=frontend service regardless of key type.

Using secrets in configs

Configs can reference secrets by key using the {{secret:KEY}} template syntax. The value is resolved server-side at sync time and delivered as the resolved string - the secret value is never stored in plaintext in the config.
A config whose value references a secret that has no value - or a secret that does not exist - is not delivered to the application until the reference resolves. See A secret without a value.

A secret without a value

A secret can be declared without a value. It has a key, a type and a description, and it shows in the console as Not set with an Add value action. Importing from develop into a personal environment creates secrets this way: a secret value never leaves its environment, so only the key travels, and a secret that already exists in the personal environment is never changed. What the application sees:
  • The secret is not delivered. The SDK reports it the way it reports any secret that is not there - an error or an absent value, depending on the SDK - never as an empty string.
  • A config that references it with {{secret:KEY}} is not delivered either, so the application never receives a half-rendered value.
  • The sync response lists what was left out in an errors array: secret_not_set for the secret, config_unresolved_secret for each config that references it, each with the key and a readable explanation.
All SDKs log each omission as a warning (when logging is enabled) and expose the list via GetSyncErrors() / getSyncErrors() / get_sync_errors(). westyx dev run names every secret without a value before it starts your process, and westyx secret list shows it as (not set). Adding the first value makes it version 1. From then on it is an ordinary secret.

Versioning

Every write to a secret creates a new version. You can:
  • View version history in the console
  • Promote an older version to become the current value
  • See the diff between versions

Live updates

Backend SDKs receive secret changes over SSE (secret.created, secret.updated, secret.deleted, secret.renamed) and trigger a fresh sync within milliseconds - including refreshing temp files on disk for file-type secrets. See Quickstart -> Enable live updates.

Audit log

The following actions are recorded in the audit log for secrets: