Namespaces
Hierarchical containers that group secrets and hold their own encryption key — creation, archiving, and key rotation.
A namespace is a hierarchical container for secrets, scoped to one project and environment.
It's the third segment of a path (acme-web / prod / product/web / …) and — importantly — it holds
its own encryption key.
Structure#
- Paths use
a–z, digits,_,-,/, up to 5 segments deep (e.g.product/web,data/etl). - A namespace is unique per
(project, environment, path)—acme-web/prod/product/webandacme-web/dev/product/webare different namespaces with independent keys.
A namespace path can be changed. Because secret values are cryptographically bound to their full path (it is the authenticated data of every encryption), a rename decrypts and re-encrypts every secret underneath it. That means the engine must be unsealed, the action is audited at HIGH severity, and it is refused if another namespace already occupies the target path.
The {project}/{env} portion above it is a permanent mount and can never be renamed. Anything
referencing the old path — policies, pipelines, --project defaults — must be updated by you.
Creating a namespace#
Namespaces → New namespace. Pick the environment, enter the path, optionally a display name and description. Creating a namespace mints a fresh Key Encryption Key, so the engine must be unsealed — if it's sealed you'll see a banner and the create action returns 503.
Requires secrets:namespace:manage.
Browsing secrets#
Open a namespace to see its secrets (metadata only — path, version, size — never the value) along with the validation status badge for each validated path. From here you can attach validation — to a folder whose keys together form one credential, or to a single key that is itself the credential. A path with no probe attached shows no badge, which is the normal state: validation is opt-in.
Rotating the encryption key#
The Rotate encryption key action re-wraps the namespace's data keys under a fresh KEK. It's:
- Safe — secret values are never touched, only the wrapping key.
- Instant — no downtime, no re-encryption of secrets.
Rotate periodically, or immediately if you suspect a key-material exposure.
Archiving#
Archiving a namespace is a soft delete — history is retained, but new writes are blocked. Use it to retire a namespace without destroying its audit trail.