Secret Sources

For HTTP routes, Cordon fetches credentials from external secret stores per request. PostgreSQL listeners currently resolve credentials at startup. Two sources are supported.

Rotation and restarts

Consumer	When the secret is resolved	Rotation behavior
HTTP routes	Startup validation, then every matched request	New values are picked up on the next request. No restart required after secret rotation.
PostgreSQL listeners	Listener startup	Restart Cordon after rotating the listener password.

Route definitions are still loaded at startup. Restart Cordon after adding, removing, or editing routes or listeners.

1Password

Fetches secrets from 1Password vaults using the 1Password CLI (op).

[routes.auth.secret]
source = "1password"
account = "my-team"
vault = "Engineering"
item = "Stripe API Key"
field = "secret_key"

Field	Required	Description
`account`	no	1Password account selector passed to `op --account`. Accepts the same identifiers as `op`: sign-in address, shorthand, account UUID, or user UUID. Recommended for multi-account and service setups.
`vault`	yes	1Password vault name within the selected account
`item`	yes	Item name within the vault
`field`	yes	Field label within the item (case-sensitive)

If account is omitted, Cordon preserves legacy behavior and lets op use its active/default account. Cordon warns about omitted accounts because that behavior is ambiguous in multi-account and background service environments.

Prerequisites

The op CLI must be installed and authenticated before starting Cordon. For installation, sign-in options, service accounts, and troubleshooting, see the 1Password guide.

Provider configuration (optional)

If op is not on PATH (common for background services), specify the binary path explicitly in the provider config:

[secrets]
[[secrets.providers]]
type = "1password"
path = "/opt/homebrew/bin/op"

OS Keyring

Reads credentials from the operating system’s built-in credential store.

[routes.auth.secret]
source = "keyring"
account = "stripe-api-key"

Field	Required	Description
`account`	yes	Account name (identifier for the credential)
`service`	no	Keyring service name. Defaults to `"cordon"` when omitted.
`decode`	no	Decoding strategy for encoded values. Currently supports `"go-keyring"`.

By default, cordon uses cordon as the keyring service name. If you inspect the OS keychain directly (e.g., macOS Keychain Access, security find-generic-password -s cordon), entries appear under the service cordon.

Reading third-party keychain entries

You can use service to read credentials stored by other tools under their own keychain entries, avoiding token duplication. For example, the GitHub CLI (gh) stores its token under service gh:github.com:

[routes.auth.secret]
source = "keyring"
account = "lightcap"
service = "gh:github.com"
decode = "go-keyring"

This reads gh’s token directly — no need to copy it into cordon’s keyring. When gh auth refresh updates the token, cordon picks up the new value automatically.

The `decode` field

Some tools encode values before storing them in the keychain. The decode field tells cordon how to decode the raw keychain value before using it.

Value	Description
`"go-keyring"`	Handles encoding from Go’s zalando/go-keyring library. Strips `go-keyring-base64:` and base64-decodes the remainder, or strips `go-keyring-encoded:` and hex-decodes the remainder. Values without a recognized prefix are used as-is.

decode is only needed when the tool that stored the credential uses an encoding wrapper. Most tools (Python, Rust, native CLI tools) store raw values and don’t need it. The go-keyring encoding is used by Go CLI tools including gh.

Storing keyring credentials

Use cordon secret set to store credentials under the default cordon service. The account name is independent of route names — cordon secret set/cordon secret delete take an account name directly and never read cordon.toml or look up routes. Use cordon route show <name> to see which account a route’s source: keyring entry references:

cordon secret set stripe-api-key
# Prompts for the secret value

On macOS, you can also use the native security CLI:

security add-generic-password -s cordon -a stripe-api-key -w 'sk_live_...'

cordon secret set always stores under the cordon service. When using a custom service to read from a third-party keychain entry, the credential is managed by that tool — you don’t need to store it via cordon.

Platform differences

macOS Keychain

macOS Keychain enforces per-application access control. The binary that creates a keychain entry owns it and can read it without prompting. Any other binary triggers a system authorization dialog.Use cordon secret set to create entries owned by cordon. Entries created by other tools (e.g., security CLI) will prompt on every request that needs the secret.Upgrading cordon, doing a fresh cargo build during development, or changing the install path changes the binary identity. macOS will prompt for keychain access the first time the new binary reads the secret. When this prompt appears, click Always Allow (not just Allow) to permanently grant the new binary access. Because cordon resolves keyring secrets just-in-time on each request, clicking “Allow” (one-time) means the prompt reappears on the very next request — which can be milliseconds later.In SSH, headless, or detached screen/tmux sessions, the keychain is locked and cannot display a prompt. Run security unlock-keychain ~/Library/Keychains/login.keychain-db first, or run the command from a terminal in a desktop session (directly or via screen sharing) where the login keychain is already unlocked. See Troubleshooting (macOS) for details.

Linux Secret Service

On Linux, cordon uses the D-Bus Secret Service API, typically provided by GNOME Keyring or KDE Wallet. Secrets are encrypted on disk and unlocked with the user’s login session. There are no per-application ACLs — any process running as the user can read entries. Security relies on standard Unix user isolation.A Secret Service provider must be installed and running:

sudo apt install gnome-keyring   # Debian/Ubuntu

After installing, log out and log back in to initialize the default “login” collection. Without this step, cordon secret set will fail with:

DBus error: Object does not exist at path "/org/freedesktop/secrets/collection/login"

A running D-Bus session bus is required — the keyring source does not work in containers, CI, or headless environments.

Troubleshooting (macOS)

Platform secure storage failure: User interaction is not allowed.

The macOS login keychain is locked. This happens in SSH sessions, headless CI, and detached screen/tmux sessions where Keychain cannot display its authorization dialog.Unlock the login keychain before running cordon secret set:

security unlock-keychain ~/Library/Keychains/login.keychain-db

This prompts for your macOS login password. Once unlocked, keychain operations work for the remainder of the session. If you have access to the Mac directly or via screen sharing, run cordon secret set from a terminal in the desktop session instead — the login keychain is already unlocked there.

Authorization prompt on every request after upgrade

macOS Keychain enforces per-application access control based on the binary identity. Any change to the cordon binary — upgrades, fresh builds during development, different install paths — triggers a new authorization prompt.Preferred fix: Re-store credentials with cordon secret set <account> so the current binary owns the entry.Quick unblock: Click Always Allow on the macOS Keychain dialog. This permanently grants the new binary access. Do not click just “Allow” — HTTP routes resolve keyring secrets per-request, so a one-time allow triggers a new prompt on every subsequent request.

Troubleshooting (Linux)

A Secret Service provider is not running or has not initialized its default collection. Fix:

sudo apt install gnome-keyring

Then log out and log back in so the keyring daemon starts and creates the “login” collection.

Platform secure storage failure

The D-Bus session bus is not available. Verify it’s reachable:

# Check for session bus address
echo $DBUS_SESSION_BUS_ADDRESS

# Or check for systemd user bus socket
ls $XDG_RUNTIME_DIR/bus

If neither is available, you’re not in a desktop session (e.g., SSH, container, or headless server). The keyring source requires a desktop session.

Keyring access timed out

The Secret Service provider is not responding. Check that gnome-keyring-daemon (or your provider) is running:

ps aux | grep gnome-keyring

If not running, log out and back in, or start it manually:

gnome-keyring-daemon --start --components=secrets

Mixing sources

You can use different secret sources for different routes:

[[routes]]
name = "stripe"

[routes.match]
host = "api.stripe.com"

[routes.auth]
type = "header"
header_name = "Authorization"
scheme = "Bearer"

[routes.auth.secret]
source = "1password"
account = "my-team"
vault = "Engineering"
item = "Stripe API Key"
field = "secret_key"

[[routes]]
name = "internal-api"

[routes.match]
host = "api.internal.example.com"

[routes.auth]
type = "header"
header_name = "X-Api-Key"

[routes.auth.secret]
source = "keyring"
account = "internal-api-key"

Getting Started

Configuration

Guides

CLI Reference

Security

Secret Sources

Rotation and restarts

1Password

Prerequisites

Provider configuration (optional)

OS Keyring

Reading third-party keychain entries

The `decode` field

Storing keyring credentials

Platform differences

Troubleshooting (macOS)

Troubleshooting (Linux)

Mixing sources

​Rotation and restarts

​1Password

​Prerequisites

​Provider configuration (optional)

​OS Keyring

​Reading third-party keychain entries

​The decode field

​Storing keyring credentials

​Platform differences

​Troubleshooting (macOS)

​Troubleshooting (Linux)

​Mixing sources

Rotation and restarts

1Password

Prerequisites

Provider configuration (optional)

OS Keyring

Reading third-party keychain entries

The `decode` field

Storing keyring credentials

Platform differences

Troubleshooting (macOS)

Troubleshooting (Linux)

Mixing sources