Secret Management for AI Provider Keys

AI provider API keys are high-value secrets — a leaked key can incur unbounded costs and expose sensitive data. Keeptrusts provides encrypted storage, rotation APIs, and integration points for enterprise secret managers.

Use this page when

You need to store AI provider API keys securely using config variables with AES-GCM-SIV encryption
You are setting up key rotation, Vault integration, or Kubernetes External Secrets Operator
You want to understand secret_key_ref resolution, naming conventions, and audit logging for secret operations

Primary audience

Primary: Technical Engineers
Secondary: AI Agents, Technical Leaders

Config Variables

Config variables are the primary mechanism for storing provider API keys. The gateway resolves secret_key_ref values through the config-variable machine endpoint at runtime.

Naming Conventions

Config variable names must contain only ASCII letters, digits, underscores, hyphens, and dots. No slashes.

# Valid names
OPENAI_API_KEY
anthropic.production.key
azure-openai-key-east-us
provider_key_v2

# Invalid names
openai/api/key        # slashes not allowed
my key                # spaces not allowed

Creating Config Variables

curl -X POST https://api.example.com/v1/config-variables \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OPENAI_API_KEY",
    "value": "sk-proj-...",
    "description": "OpenAI production API key",
    "sensitive": true
  }'

When sensitive is true, the value is encrypted at rest and redacted in API responses and audit logs.

Referencing in Gateway Config

pack:
  name: secret-management-providers-1
  version: 1.0.0
  enabled: true
providers:
  targets:
  - id: openai
    provider: 
policies:
  chain:
  - audit-logger
policy:
  audit-logger:
    immutable: true
    retention_days: 365
    log_all_access: true

The gateway resolves OPENAI_API_KEY from config variables at startup and on config reload. The plaintext key never appears in the configuration file or gateway logs.

Encryption at Rest

AES-GCM-SIV

Keeptrusts encrypts sensitive config variables, Git access tokens, and webhook secrets using AES-GCM-SIV (RFC 8452). This authenticated encryption scheme provides:

Nonce misuse resistance — safe even if a nonce is accidentally reused
Authenticated encryption — tamper detection built in
256-bit key strength — resistant to brute force

The encryption key is derived from KEEPTRUSTS_SECRET_ENCRYPTION_KEY environment variable, which must be set on the API server.

Legacy Plaintext Handling

For backward compatibility, the API can read legacy plaintext rows. On any update, the value is automatically re-encrypted with AES-GCM-SIV. No manual migration is required.

Key Rotation API

Rotating Provider Keys

Rotate a provider key without gateway downtime:

# Step 1: Create the new key as a config variable
curl -X POST https://api.example.com/v1/config-variables \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OPENAI_API_KEY_V2",
    "value": "sk-proj-new-...",
    "sensitive": true
  }'

# Step 2: Update the gateway config to reference the new variable
# In policy-config.yaml:
# secret_key_ref:
#   store: OPENAI_API_KEY_V2

# Step 3: Reload the gateway config
kt gateway reload --name keeptrusts-proxy --gateway-url http://localhost:41002

# Step 4: Verify the new key is active
kt gateway status

# Step 5: Delete the old config variable
curl -X DELETE https://api.example.com/v1/config-variables/OPENAI_API_KEY \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Rotating the Encryption Key

To rotate the master encryption key:

Stage the replacement value in your secret manager or deployment manifest.
Restart the API server with the new KEEPTRUSTS_SECRET_ENCRYPTION_KEY value.
Verify secret reads and writes succeed after the restart.
Remove the superseded key material from any staging locations once validation is complete.

Rotating JWT Signing Keys

The API supports JWT key rotation via the kid header:

# Set multiple verification keys (comma-separated key IDs)
export KEEPTRUSTS_JWT_VERIFICATION_KEYS="kid1:secret1,kid2:secret2"

New tokens are issued with the latest kid. Old tokens remain valid until expiry as long as their kid is in the verification key set.

Environment Variable Injection

Gateway Process

For provider keys not stored in config variables, inject them directly as environment variables:

# Direct injection
export OPENAI_API_KEY="sk-proj-..."
kt gateway run --listen 0.0.0.0:41002 --policy-config policy-config.yaml

When using secret_key_ref.env:

pack:
  name: secret-management-providers-2
  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:
        env: OPENAI_API_KEY
policies:
  chain:
    - audit-logger
policy:
  audit-logger:
    immutable: true
    retention_days: 365
    log_all_access: true

The env var must be available in the gateway process. Note: secret_key_ref is validated at config parse time, failing fast if the variable is missing.

Kubernetes Secrets

Map Kubernetes secrets to gateway environment variables:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: keeptrusts-gateway
spec:
  template:
    spec:
      containers:
        - name: gateway
          envFrom:
            - secretRef:
                name: keeptrusts-provider-keys
          env:
            - name: KEEPTRUSTS_SECRET_ENCRYPTION_KEY
              valueFrom:
                secretKeyRef:
                  name: keeptrusts-master
                  key: encryption-key

Create the Kubernetes secret:

kubectl create secret generic keeptrusts-provider-keys \
  --from-literal=OPENAI_API_KEY="sk-proj-..." \
  --from-literal=ANTHROPIC_API_KEY="sk-ant-..." \
  -n keeptrusts

HashiCorp Vault Integration

External Secrets Operator

For Vault-managed secrets, use the Kubernetes External Secrets Operator:

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: keeptrusts-provider-keys
  namespace: keeptrusts
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: vault-backend
    kind: ClusterSecretStore
  target:
    name: keeptrusts-provider-keys
  data:
    - secretKey: OPENAI_API_KEY
      remoteRef:
        key: secret/data/keeptrusts/providers
        property: openai_api_key
    - secretKey: ANTHROPIC_API_KEY
      remoteRef:
        key: secret/data/keeptrusts/providers
        property: anthropic_api_key
    - secretKey: KEEPTRUSTS_SECRET_ENCRYPTION_KEY
      remoteRef:
        key: secret/data/keeptrusts/master
        property: encryption_key

Vault Agent Sidecar

Alternatively, use the Vault Agent injector:

annotations:
  vault.hashicorp.com/agent-inject: "true"
  vault.hashicorp.com/role: "keeptrusts-gateway"
  vault.hashicorp.com/agent-inject-secret-providers: "secret/data/keeptrusts/providers"
  vault.hashicorp.com/agent-inject-template-providers: |
    {{- with secret "secret/data/keeptrusts/providers" -}}
    export OPENAI_API_KEY="{{ .Data.data.openai_api_key }}"
    export ANTHROPIC_API_KEY="{{ .Data.data.anthropic_api_key }}"
    {{- end }}

Audit Trail

All secret operations are logged in the audit trail:

Config variable creation, update, and deletion
Encryption key rotation events
Gateway config reloads that resolve new key references
Failed key resolution attempts

Query the audit log:

kt events list --filter 'category=secret_management' --limit 50

Security Checklist

All provider keys stored as sensitive config variables or Kubernetes secrets
KEEPTRUSTS_SECRET_ENCRYPTION_KEY set on all API instances
JWT verification keys support rotation via kid
Provider keys rotated on a quarterly schedule minimum
No plaintext keys in gateway config files or environment dumps
Audit log retained for secret operations per compliance requirements
Vault or External Secrets Operator configured for production environments

Next steps

Configure Disaster Recovery for encryption key backup
Set up Monitoring & Alerting for failed key resolution alerts
Review Compliance Infrastructure for secret audit requirements

For AI systems

Canonical terms: config variables, secret_key_ref, AES-GCM-SIV, KEEPTRUSTS_SECRET_ENCRYPTION_KEY, key rotation, sensitive flag, nonce misuse resistance
API endpoints: POST /v1/config-variables, key rotation API
Config reference:
```
secret_key_ref:
  store: VAR_NAME
```
Naming rules: ASCII letters, digits, underscores, hyphens, dots only — no slashes or spaces
Integration points: HashiCorp Vault, Kubernetes External Secrets Operator, AWS Secrets Manager
Related pages: Disaster Recovery, Monitoring & Alerting, Compliance Infrastructure

For engineers

Create sensitive config variables with POST /v1/config-variables and "sensitive": true — values encrypted at rest, redacted in API responses
Reference in gateway config as:
```
secret_key_ref:
  store: OPENAI_API_KEY
```
The value is resolved at startup and on config reload.
KEEPTRUSTS_SECRET_ENCRYPTION_KEY must be set on all API instances; losing it makes encrypted secrets unrecoverable
Legacy plaintext rows are auto-encrypted on next update — no manual migration needed
For Kubernetes, use External Secrets Operator to sync from Vault/AWS into K8s Secrets, then mount as env vars
Validate: after rotation, send a request through the gateway and confirm the provider responds (not 401)
Audit: kt events list --filter 'category=secret_management' shows rotation, resolution, and access events

For leaders

AI provider keys are high-value secrets — a leaked key creates unbounded cost exposure and data risk
AES-GCM-SIV encryption at rest provides nonce-misuse resistance and tamper detection
Key rotation API enables quarterly rotation without gateway downtime
Vault/External Secrets integration supports enterprise secret governance requirements
Audit logging for all secret operations satisfies SOC 2 CC6 access control evidence needs
Security checklist: no plaintext keys in configs, encryption key backed up separately, rotation on schedule

Use this page when​

Primary audience​

Config Variables​

Naming Conventions​

Creating Config Variables​

Referencing in Gateway Config​

Encryption at Rest​

AES-GCM-SIV​

Legacy Plaintext Handling​

Key Rotation API​

Rotating Provider Keys​

Rotating the Encryption Key​

Rotating JWT Signing Keys​

Environment Variable Injection​

Gateway Process​

Kubernetes Secrets​

HashiCorp Vault Integration​

External Secrets Operator​

Vault Agent Sidecar​

Audit Trail​

Security Checklist​

Next steps​

For AI systems​

For engineers​

For leaders​