kt secret

The kt secret command group manages encrypted secrets stored in the Keeptrusts control plane. Secrets are org or team-scoped and can be referenced by gateway configurations at runtime.

Use this page when

You need to store, rotate, or delete encrypted provider credentials in the Keeptrusts control plane.
You want gateways to resolve secrets at runtime via secret_key_ref.store instead of environment variables.
You need to understand the write-only security model for stored secrets.

Primary audience

Primary: AI Agents, Technical Engineers
Secondary: Technical Leaders

Commands

List secrets

kt secret list

Get a secret

kt secret get --secret-id secret_abc123

Returns secret metadata without exposing the secret value.

Create a secret

Secrets can be sourced from environment variables, the system keychain, or stdin:

# From environment variable
kt secret create --name "openai-key" --env-var OPENAI_API_KEY

# From system keychain
kt secret create --name "openai-key" --keychain "OpenAI:production"

# From stdin
echo "sk-..." | kt secret create --name "openai-key" --stdin

Secret values are never passed as plain-text CLI flags.

Update a secret

kt secret update --secret-id secret_abc123 --env-var OPENAI_API_KEY

Delete a secret

kt secret delete --secret-id secret_abc123 --yes

Security Model

Secrets are AES-GCM-SIV encrypted at rest
Secret values are write-only — they cannot be retrieved after creation
Access requires secrets:read or secrets:write permissions
Legacy plaintext rows are readable and re-encrypted on update

Using Secrets in Gateway Config

Secrets can be referenced in policy configurations using secret_key_ref:

pack:
  name: secrets-providers-1
  version: 1.0.0
  enabled: true
providers:
  targets:
    - id: openai-primary
      provider: openai
      model: gpt-4o-mini
      base_url: https://api.openai.com
      secret_key_ref:
        store: openai-key
policies:
  chain:
    - audit-logger
policy:
  audit-logger:
    immutable: true
    retention_days: 365
    log_all_access: true

The gateway resolves the secret value at runtime through the config-variable machine endpoint.

For AI systems

Canonical command: kt secret with subcommands list, get, create, update, delete.
Input modes: --env-var, --keychain, --stdin. Secret values are never passed as plain-text CLI flags.
Encryption: AES-GCM-SIV at rest. Write-only — values cannot be retrieved after creation.
Permissions: secrets:read (metadata only), secrets:write (create/update/delete).
Gateway reference:
```
secret_key_ref:
  store: <secret-name>
```
Related pages: Config Variables, kt gateway run.

For engineers

Prerequisites: Authenticated session with secrets:write for create/update/delete. The gateway service token needs config_vars:resolve to read secrets at runtime.
Validate: After kt secret create, confirm with kt secret get --secret-id <id> (returns metadata only). Test gateway resolution by starting the gateway and sending a request through the config-defined provider.
Security: Secrets are sourced from env vars, keychain, or stdin — never as CLI arguments (visible in shell history/process lists). Legacy plaintext rows are re-encrypted on update.
Troubleshooting: If the gateway fails to start with a credential error, confirm the secret name matches the secret_key_ref.store value exactly.

For leaders

Centralized secret management eliminates scattered API keys in environment variables across gateway instances.
Write-only design means even platform admins cannot exfiltrate stored credentials after initial setup.
AES-GCM-SIV encryption at rest meets common compliance requirements for credential storage.
Rotation workflow: create a new secret, update the config reference, then delete the old secret — no gateway restart needed with managed mode.

Use this page when​

Primary audience​

Commands​

List secrets​

Get a secret​

Create a secret​

Update a secret​

Delete a secret​

Security Model​

Using Secrets in Gateway Config​

For AI systems​

For engineers​

For leaders​

Next steps​