Secret vault

Credentials are sealed when they are written and no endpoint ever returns them. Only the worker opens them, at the moment of an outgoing call.

The vault holds the credentials you enter: a model provider key, the token of an HTTP tool or of an MCP server, the token of a source connector, a Slack token entered by hand, the signing secret of a scheduled webhook. It uses envelope encryption: each secret is encrypted with its own data key (AES-256-GCM), and that key is encrypted with the public key of the instance's sealing key pair (RSA-OAEP).

The sealing key pair is split between the 2 services. The API server receives the public key (RIKOO_SECRETS_PUBLIC_KEY): it can seal a value, not open it. Only the worker holds the private key (RIKOO_SECRETS_PRIVATE_KEY, or a file with RIKOO_SECRETS_PRIVATE_KEY_FILE).

Credentials that Rikoo obtains itself, rather than ones you type, are sealed in the same envelope but stored with the resource they belong to: the OAuth tokens of an MCP server, the Slack tokens obtained by installing the app, the signing secrets of outgoing webhooks.

The rules

• Write-only from the outside. No endpoint returns the value of a secret. The Secrets screen shows its name, its type, its scope (a project or the whole organization) and the last 4 characters of the value as a hint.
• The API server never decrypts. Only the worker does, only in the stack of an outgoing call, and it removes the value from its own log lines.
• Every access is audited. A secret_accessed entry records which secret was opened, for which run, and when. It is written before the value is handed over: if the entry cannot be written, the access is refused.
• A referenced secret cannot be deleted. Deletion is refused as long as a model provider, an HTTP tool, an MCP server, a source or an agent schedule still points to it.
• An expired secret stays closed. When a secret has an expiry date, the worker refuses to open it once the date has passed.

Protecting the sealing key pair is up to you

No key pair ships with Rikoo: you generate it when you install the platform (see Docker Compose or Kubernetes (Helm)). Outside production, if the public key is missing, the API server makes a temporary pair and the vault turns read-only: the Secrets screen says so and refuses new secrets. In production the pair is required. Keep the private key out of images, prefer the file variant, and back it up somewhere other than the database it protects. Losing the private key makes every sealed value unreadable, and the credentials must then be entered again.

Rotation

To replace a credential, use Rotate the value on the Secrets screen and paste the new value. Nothing has to be re-entered elsewhere, because providers, tools and servers reference the secret, not its content. The expiry date follows the value: rotation can set a new one, or clear it.

The previous value stays sealed for 24 hours, then it is purged. During that window it is used only to verify incoming signatures that were produced before the rotation; it is never sent to a third party. Model providers that use the rotated secret are marked as needing a new connection test.

Rotating the sealing key pair itself is an operator task. The worker keeps the previous private keys in RIKOO_SECRETS_PRIVATE_KEYS_PREVIOUS until the re-wrap job (make secrets-rewrap) has re-sealed every data key with the new pair.