applications & projects/Secrets/Managed Secrets

Managed Secrets

Keep one database or cache account synchronized with an agent-confirmed password rotation workflow.

Updated today

Managed secrets keep one long-lived service account synchronized between SikkerKey and a supported database or cache. SikkerKey generates the password, a SikkerKey agent applies it to the provider, and applications read the current username and password from SikkerKey.

A managed secret always contains two fields: username and password. The username stays fixed while SikkerKey rotates the password.

#How managed secrets work

Each managed secret combines an encrypted credential, a provider connection, a rotation schedule, and one registered agent machine. The agent runs on a machine that can reach the database over your network.

SikkerKey generates a new password and holds it as a pending rotation.

The agent retrieves the pending credential and connects to the provider with the administrative account entered during setup.

The agent creates the managed account when supported and needed, or updates the password of the existing account.

The agent signs in with the managed username and new password to verify the change.

After successful verification, SikkerKey makes the pending credential current and records a new secret version.

Applications continue to receive the current confirmed version while a rotation is pending. A newly generated password is exposed to consumers only after the provider has accepted and verified it.

Part	Purpose
Managed secret	Stores the fixed username and current confirmed password
Provider connection	Gives the agent the host, port, database, and administrative credentials needed to update the account
Agent machine	Runs close to the provider, applies password changes, verifies them, and reports health
Rotation schedule	Controls when a new password is generated and what shape it uses
Machine grant	Allows a machine to read the managed secret; the agent machine also requires this grant
Version history	Records version 1 and every successfully confirmed rotation

#Supported providers

Provider	Account behavior
PostgreSQL	Updates the named login role. If the role does not exist, the agent creates it with login access.
PostgreSQL (Supabase)	Uses the Supabase project reference for pooler routing, then updates or creates the named PostgreSQL role.
MySQL	Updates the named user at the % host. If it does not exist, the agent creates it.
Redis	Updates the default user password or a named Redis 6+ ACL user. A new named user is enabled with access to all keys and commands.
MongoDB	Updates the named user in the selected database. If it does not exist, the agent creates it with readWrite access to that database.

Create and grant the managed account in advance when you need provider-specific permissions. The agent preserves an existing account’s assigned permissions while changing its password.

Administrative account requirements

PostgreSQL: an account with CREATEROLE or SUPERUSER.
MySQL: an account with CREATE USER or ALL PRIVILEGES.
Redis: an account allowed to run the required ACL commands, or CONFIG SET requirepass for Redis versions before ACL support.
MongoDB: an account that can list, create, and update users in the selected database.

For PostgreSQL (Supabase), enter the 16–32 character lowercase project reference shown in the Supabase pooler hostname. The agent uses that reference when connecting through Supavisor.

#Prepare the agent machine

Use a persistent machine with the SikkerKey CLI installed and network access to the provider host and port. The machine must be connected to the same vault, belong to the managed secret’s project, and have an explicit grant for the managed secret.

Connect and approve the machine in SikkerKey.

Add the machine to the project that will contain the managed secret.

After creating the managed secret, configure the machine and grant that secret to it.

Confirm the machine can reach the provider using the host and port you will enter in SikkerKey.

The first eligible machine that starts the agent for a managed secret becomes its registered rotation agent. Keep one agent running for each managed secret.

#Create a managed secret

Open the project that should own the credential, then open Secrets.

Select the plus button and choose Managed Secret.

Enter a name and select PostgreSQL, PostgreSQL (Supabase), MySQL, Redis, or MongoDB.

Enter the provider host, port, database, administrative username, and administrative password.

For PostgreSQL (Supabase), enter the project reference used by the Supabase pooler.

Continue to Role & rotation and enter the username or role whose password SikkerKey will manage.

Choose Random or UUID password generation. For Random, choose a length and the character groups to include.

Choose how often the password should rotate.

Review the connection, managed role, and schedule, then select Create managed secret.

The managed username must begin with a letter or underscore and may contain letters, numbers, and underscores, up to 63 characters. Rotation intervals can range from 5 minutes to 30 days. New managed secrets default to a 32-character password using uppercase letters, lowercase letters, and numbers, with a daily rotation.

Creation stores version 1 and starts the schedule. Complete the agent setup and perform the first confirmed rotation before directing an application to the managed credential.

#Start the agent

Open the managed secret’s row menu, select Configure, and open Agent. The dashboard provides commands containing the secret ID.

Install as a background service

bash

sudo sikkerkey agent install --secret <secret_id> --now

This installs and starts an operating-system service so the agent starts with the machine and restarts after a failure.

Run in the foreground

bash

sikkerkey agent start --secret <secret_id>

Use the foreground command while validating setup or observing the first rotation. Keep the terminal open while it runs.

At startup, the agent retrieves the encrypted connection configuration through its authenticated machine identity, tests the administrative connection, and reports Healthy when it is ready. It checks for pending rotations every 10 seconds and sends a health update every 30 seconds.

#Complete the first synchronization

After the Agent tab shows Healthy, run an immediate rotation to establish the same password in the provider and SikkerKey.

Open Configure for the managed secret.

Open Schedule.

Select Rotate now.

Wait while the status shows Rotation pending.

Confirm that the pending status clears, the agent remains Healthy, and the secret version increases.

Grant the managed secret to each application machine that needs the credential.

The agent updates or creates the provider account, verifies a new connection with the managed credential, and confirms the rotation. The resulting username and password are then ready for application use.

#Manage the rotation schedule

Open Configure, then Schedule, to review and change rotation.

Rotate every sets the cadence.
Generated value selects Random or UUID. Random passwords can use uppercase letters, lowercase letters, numbers, and symbols.
Save schedule applies the new cadence and password shape.
Pause rotation keeps the current confirmed credential while stopping scheduled password changes.
Resume rotation starts scheduled changes again.
Rotate now starts a rotation immediately when the schedule is active and no rotation is already pending.
Last rotated shows the latest successfully confirmed change.
Next shows the next scheduled attempt.

Changing the schedule recalculates the next rotation time. A paused schedule can be edited and then resumed when you are ready.

#Understand agent and rotation status

Status	Meaning	Action
No agent	No machine has connected as the rotation agent.	Start the agent on the prepared machine.
Healthy	The agent is connected, can reach the provider, and is reporting normally.	Scheduled and immediate rotations can proceed.
Unhealthy	The latest health update is stale.	Check that the service and machine are running and can reach SikkerKey.
Sync error	The agent reported a connection, apply, verification, or confirmation error.	Review the displayed error and the agent service logs, correct the cause, then retry.
Rotation pending	A password is waiting for the agent to apply and verify it.	Keep the agent running until it confirms or rejects the rotation.
Rotation failed	The provider did not accept or verify the pending credential.	Correct the provider or network issue, select Retry rotation, then use Rotate now for an immediate new attempt.
Active	Scheduled rotation is enabled.	Review the last and next rotation times as needed.
Paused	Scheduled rotation is disabled.	Select Resume rotation when rotations should continue.

If applying a password fails, SikkerKey keeps the current confirmed version. If applying succeeds but verification fails, the agent attempts to restore the previous provider credential before reporting the failure.

#Use a managed secret in an application

A managed secret is retrieved as a structured value with username and password fields. Applications can read the complete object or select either field through a SikkerKey SDK.

Add the application machine to the managed secret’s project.

Grant the managed secret to that machine.

Read the secret by its stable secret ID from the SikkerKey SDK or CLI integration used by the application.

Map the username and password fields into the application’s database or cache connection.

Refresh or restart connection pools when your application observes a new secret version.

Keep provider credentials out of application configuration files. Let each authorized runtime retrieve the current confirmed version from SikkerKey.

Machine grants and an attached access policy are evaluated when a machine reads the credential. The grant applies to both fields as one secret.

#Delete a managed secret

Deleting a managed secret stops its rotation schedule, removes its agent connection configuration and machine grants, and moves the encrypted secret and version history to Trash for 30 days. The running agent exits after it can no longer retrieve the configuration.

Open the managed secret’s row menu and select Delete.

Review the machines that will lose access.

Confirm the deletion.

Restoring from Trash recovers the retained secret record and version history in its original project. Create a new managed secret when you need to establish a new provider connection, agent registration, and rotation schedule.

Permanent deletion from Trash, or automatic cleanup after 30 days, removes the managed secret and every retained version.

#Permissions

Permission	Access provided
Project in scope	View managed-secret metadata, agent and rotation status, versions, machine count, policy, and activity
Manage managed secrets	Create, update, rotate, pause, resume, retry, rename, and delete managed secrets
Configure machine grants	Choose which project secrets a machine can read, including the grant required by the agent
Manage policies	Attach, remove, and configure access policies according to the role’s policy capabilities
Manage own Trash	Restore or permanently delete managed secrets the member deleted
Manage all Trash	Manage every deleted secret in the vault

Vault owners receive full access. Organization members receive project scope and managed-secret capabilities through their access role. Trash access comes from the vault role.

#Troubleshoot managed secrets

Symptom	What to check
Agent stays at No agent	Confirm the CLI machine is connected and approved, belongs to the project, has an explicit grant for the managed secret, and is running the command shown in the Agent tab.
Agent reports Access denied	Confirm the machine belongs to the same vault and project and still has the managed-secret grant. Review whether the project is locked.
Another machine is already registered	Run the agent on the original registered machine. One machine is registered as the rotation agent for each managed secret.
Connection test fails	Check the provider host, port, database, administrative username and password, network route, and administrative permissions.
Status becomes Unhealthy	Check the agent service and machine network. The dashboard marks a previously healthy agent unhealthy after health updates stop.
Rotation remains pending	Confirm the agent is running and can reach both SikkerKey and the provider. Review its service logs for the pending rotation.
Rotation fails while applying	Confirm the administrative account can create or update the named account and that the managed username is valid for the provider.
Rotation fails during verification	Confirm the managed account can sign in to the selected database from the agent machine and that the provider accepts the generated password shape.
Application cannot connect after rotation	Refresh its SikkerKey value and connection pool, then confirm it is using the current username and password fields.
Rotate now does not create a pending rotation	Confirm the schedule is active and the agent status is Healthy, then try again.