Secret and Credential Management
Keeptrusts has two supported command groups for credentials used by gateway configuration.
kt secret: hosted secret records
Use kt secret when you want Keeptrusts to store a secret record that a
connected gateway can reference by name through secret_key_ref.store.
Common commands
kt secret list
kt secret get --secret-id 00000000-0000-4000-a000-000000000101
kt secret create --name KEEPTRUSTS_OPENAI_API_KEY --env-var KEEPTRUSTS_OPENAI_API_KEY
printf 'updated-secret' | kt secret update --secret-id 00000000-0000-4000-a000-000000000101 --stdin --json
kt secret delete --secret-id 00000000-0000-4000-a000-000000000101 --yes
Input sources
kt secret create and kt secret update read secret material from one of these supported sources:
--env-var <VAR_NAME>--keychain <service:account>--stdin
create requires exactly one value source. update can change only the
description, or can replace the value from exactly one source. The keychain
source reads a macOS service:account entry. Hosted secret commands require
API authentication, and get returns metadata only—not raw secret material.
kt secrets: local provider credential resolution
Use kt secrets when you are preparing a local runtime and want to load or inspect credentials from your workstation.
Add a local provider credential
kt secrets add KEEPTRUSTS_OPENAI_API_KEY --keychain
The command prompts without echo and stores the value in the macOS Keychain. Keychain storage is currently the only backend; this command returns an unsupported error on other operating systems. When stdin is not a terminal, the command reads one line from the pipe.
Check resolution status for a config
kt secrets status --config policy-config.yaml
Output shows which provider targets are satisfiable from local environment or keychain resolution. Store-backed references are reported as unknown because this local status command does not call the API. Missing credentials are printed in the table but do not currently make the command exit non-zero.
Retired config-variable commands
The old config-variable command family is not a supported non-secret value
store. The current API returns 410 Gone for its retired endpoint and points
clients to /v1/secrets. Put non-secret settings in the declarative config
section that owns them; use kt secret only for values that must remain secret.
Validate the current config surface
Once credentials are in place, validate the resolved runtime view:
kt gateway check --config policy-config.yaml --verbose
Use this to parse the config and print provider readiness. A required missing
credential is reported as Status: Not Ready, but the command currently still
returns success; automation must inspect the output rather than relying on its
exit code.
Which command should I use?
| Need | Command |
|---|---|
| Store a hosted secret record | kt secret |
| Add a local workstation credential | kt secrets add |
| Check local credential resolution for a config | kt secrets status |
| Set a non-secret runtime option | Edit the owning field in policy-config.yaml |
| Validate the resolved gateway config | kt gateway check |