Managed Secrets

A managed secret is a credential that SikkerKey rotates on a schedule and applies to an external database automatically. When the password rotates, the CLI agent connects to your database and runs the appropriate command (e.g. ALTER ROLE ... WITH PASSWORD ... for PostgreSQL) so the new credential is live everywhere.

This solves the gap where you rotate a password in your secrets manager but your database still has the old one.

How It Works

1. You create a managed secret from the dashboard, specifying the database provider, connection details, and which role to manage
2. SikkerKey creates a structured secret with username and password fields, generates the initial password, and starts a rotation schedule
3. You run the SikkerKey CLI agent on a machine that has network access to the database
4. The agent fetches the sync configuration from SikkerKey, connects to the database locally, and applies credential changes when rotations happen
5. The agent sends heartbeats so you can monitor its health from the dashboard

The agent runs locally next to your database. Your database is never exposed to the internet.

Supported Providers

Creating a Managed Secret

From the secrets page, click + New Secret and select Managed Secret.

1. Select a provider

Choose the database type (e.g. PostgreSQL).

2. Connection details

Enter the connection details that the agent will use to connect to your database:

• Host: the database hostname or IP (as reachable from the machine running the agent)
• Port: database port (e.g. 5432 for PostgreSQL)
• Database: the database name
• Admin username: a database user with permission to create and alter roles (needs CREATEROLE or SUPERUSER)
• Admin password: the admin user's password

The connection details are encrypted with SikkerKey's server-side encryption key and are only decrypted when the agent fetches them.

3. Managed credentials

• Username / role name: the database role whose password SikkerKey will manage. Must be a valid identifier (letters, digits, underscores, max 63 characters). If the role doesn't exist, the agent creates it on first run.
• Password: auto-generated by SikkerKey on each rotation.

The agent will ALTER ROLE on every rotation. This is a cluster-wide operation in PostgreSQL -- it affects the role across all databases. Make sure no other service depends on this role's current password without reading it from SikkerKey.

4. Rotation schedule

Configure how often the password rotates (minimum 5 minutes), the generated length, and charset.

Running the Agent

After creating a managed secret, the dashboard shows CLI commands to run the agent.

Install as a service (recommended)

sudo sikkerkey agent install --secret sk_abc123 --now

This generates and installs a system service (systemd on Linux, launchd on macOS, NSSM or sc.exe on Windows) that starts the agent automatically and restarts it on failure.

Run in the foreground

sikkerkey agent start --secret sk_abc123

The agent blocks until interrupted. Useful for testing.

What the agent does

1. Authenticates with SikkerKey using the machine's Ed25519 identity (same as SDK/CLI)
2. Fetches the sync configuration (provider, connection details, managed role)
3. Tests the database connection and verifies the admin user has sufficient privileges
4. Reports its initial status via heartbeat
5. Polls for secret value changes every 10 seconds
6. When the password rotates, connects to the database and applies the new credential
7. Sends heartbeats every 30 seconds so the dashboard can show agent health

The machine running the agent must be bootstrapped (sikkerkey connect + sikkerkey unlock) and have an explicit grant to the managed secret, just like any other secret access.

Agent Status

The dashboard shows the agent's health next to each managed secret:

Status changes are audit-logged as agent_status_change.

Other Agent Commands

# List running agents on this machine
sikkerkey agent list

# Stop an agent
sikkerkey agent stop --secret sk_abc123

# Remove agent config
sikkerkey agent remove --secret sk_abc123

# Test database connection without starting the agent
sikkerkey agent test --secret sk_abc123

Manual Configuration

For advanced setups, you can configure the agent locally instead of using the dashboard's sync config:

sikkerkey agent configure \
  --secret sk_abc123 \
  --provider postgresql \
  --host localhost \
  --port 5432 \
  --database mydb \
  --admin-user postgres \
  --admin-pass s3cret

When both local config and server-side config exist, the local config takes precedence.

Limitations

• Managed secrets are always structured with two fields: username and password
• Manual replace and rotate are disabled -- the rotation schedule controls all value changes
• The agent must have network access to the database (it connects locally, not through SikkerKey)
• One agent per managed secret per machine (use sikkerkey agent install to run as a service)

Everything Else

Version history, deletion, machine access, and encryption work identically to other secret types. Deleting a managed secret cancels the rotation schedule, removes the sync configuration, and soft-deletes the secret. The agent will stop on its next heartbeat attempt.