Secrets

There are two different sources of secret values.

Plugin secret setting

Declare a timon.settings field with type: "secret". The user enters it in Settings. With the settings permission, the host calls ctx.settings.get(key) to obtain its value. It is sealed at rest in plugin storage. The browser receives an empty value and a configured flag, not the plaintext.

Vault secret

Request secrets:read and call await ctx.secrets.get(name). Names are environment-variable identifiers, such as ACME_TOKEN. A grant to agent:plugin:<id> names that plugin specifically. Global grants are visible; grants to another agent, plugin or project do not implicitly grant your plugin access.

A vault lookup with no applicable grant returns undefined. A lookup without the declared permission throws a permission error. The API is asynchronous, so always await it.

Keep plaintext on the host

Never log secret values, even partially, or return them from a route. A broker-mode secret never leaves the daemon through a name lookup. Browser code should receive only the result of the authorised operation or a configured/not-configured status.

Use Permissions to understand caller identity and operator limits before building an outbound integration. A transport stores vault names in its connection configuration, not plaintext credentials.