03 · SECRET MANAGER

A secret's value only exists in your Agent.

The Heimdall API governs the name, the version, who may read it and who did — and refuses to receive the value. The Agent stores the value under a key you hold, and only serves a read it managed to record.

Talk to engineering

Opens a WhatsApp chat. Prefer email? heimdall@yops.cloud

What it does

The API doesn't accept the value

Creating and updating a secret writes the metadata to the API and the value to the Agent, through the CLI. A request that carries the value to the API comes back with 400 VALUE_NOT_ACCEPTED. The Console never shows or receives a value.

Who read it, which version, from where

Every read the Agent serves becomes a record: who read it, when, which version, in which environment, served by which Agent and from which address. The Agent refuses to serve a read it couldn't record — so a gap in the sequence means "read and not reported", and becomes an audit event.

When someone leaves

Removing a person from the organization marks at_risk every secret they read that hasn't changed since, in each environment where they read it, and notifies the organization. Writing a new value in an environment clears the mark for that environment, and only that one.

When a value leaks

The leaked version is deactivated: the Agent replaces the value with a record saying only that it was deactivated, and starts answering 410. Every Agent in the organization learns of it on its next sync. Nothing falls back to the previous version, because that is a credential someone already replaced.

Personal secrets

A personal secret can only be reached by its owner, through her client certificate. No token and no role open it — not even the organization's owner — and only she can read its access trail.

In the application, without a `.env` file

heimdall run starts a program with the project's secrets as environment variables, read from the Agent on the spot; the heimdall.yaml that names them holds no secret and can go into the repository. On Kubernetes, the External Secrets Operator reads straight from the Agent, with a read-only token.

Deleting without leaving a copy behind

Every Agent tells the API what its store holds — never the value. While an Agent that will not sync again may hold a copy, deleting the secret is refused with 409 VALUE_MAY_PERSIST, naming the Agent.

Database password rotation

Each Database Manager service user password is created in the Agent and rotated there, on a schedule, with a grace period for the application to pick it up.

How it works

One read, from command to record:

The CLI asks for the value from the local API of the Agent that holds that environment, with the person's client certificate.
The Agent decides with the organization's policy, which reached it through sync. It keeps deciding with the API down, for up to 24 hours.
The Agent records the read in its own store. If it can't record it, it doesn't serve it.
The value goes to the CLI. On the next sync round — 60 seconds by default — the record goes to the API. The value never travels on that channel.

TERMINAL$ heimdall secret access-log db-password

ACCESSED_AT           ACCESSOR                ENVIRONMENT  VERSION  SERVED_BY   FROM       READS
2026-10-10T06:18:58Z  agent site-agent        prod         3        site-agent  127.0.0.1  1
2026-10-10T06:18:45Z  admin@demo.example.com  prod         2        site-agent  127.0.0.1  1
2026-10-10T06:18:45Z  admin@demo.example.com  prod         3        site-agent  127.0.0.1  1

Real output of heimdall secret access-log.

Where the data lives

Everything runs in your infrastructure. The split below matters inside your company: it says who on your team can reach what.

Secret Manager: where the data lives
IN THE AGENT	IN THE API, WHICH IS YOURS
The value of each `secret`, at its current version. The store — PostgreSQL or DynamoDB — is encrypted as a whole under a 32-byte master key you hold: in a variable, a file, or an AWS KMS key, in which case the key material never leaves KMS. The local record of every read.	The name, type, description, tags and status. Each version number, per `environment`, and who created it. The linked Components. Who read each version. What each Agent reports holding — the name, the version, whether it was deactivated — without the value.

That is why nobody can recover a value through the API — not Yops, not you. Backing up the store and the master key stays with your team.

See security

Who approves what

Secret Manager: who approves what
ACTION	WHO
Read an organization's `secret`	every member, by default. A `forbid` `policy` restricts it — for example, `production`
Create, update, delete and deactivate a version	`owner` and `admin`, by default
Read the trail of who read it	`owner` and `admin`
Read a personal `secret` and its trail	only its owner
Decide which Agents hold each `environment`	`owner`
Decide what each program reaches	whoever runs the Agent: one token per program, with scope and verbs (`read`, `write`, `delete`)

With the other modules

01

Catalog

A secret can be linked to the Components that use it.
02

Infrastructure Manager

A cloud account's static credential is a secret in the Agent, and Terraform reads it from there.
04

Database Manager

Each database's administrative credential is a secret in the Agent, and every service user password is created and rotated there.
06

Release Manager

The Argo CD token the Agent uses is a secret in the Agent; the API only knows the Application's name.

Talk to the people who build Heimdall.

Tell us how your engineers store secrets and reach the database today. We'll answer with what Heimdall would put under rules first, and how the deployment would get there.