Secret management

Secrets that leak into logs, source code, or model context cannot be unleaked. Handle them before they reach your agent.

#Never log secrets

@agentskit/observability redacts nothing by default. Add a PII redactor as an observer or pre-process spans before they leave your process.

import { createPIIRedactor, DEFAULT_PII_RULES } from '@agentskit/core/security'

const redactor = createPIIRedactor({
  rules: [
    ...DEFAULT_PII_RULES,
    // API keys, bearer tokens, etc.
    { name: 'BEARER', pattern: /Bearer\s+[A-Za-z0-9\-._~+/]+=*/g, replacement: '[BEARER]' },
  ],
})

// Wrap any string before logging or tracing
const safeText = redactor.redact(rawContent)

See PII redaction for the full rule set and pipeline integration.

#Env vars, not literals

Never hard-code credentials in source files or tool schemas.

// Bad
const adapter = openai({ apiKey: 'sk-live-abc123' })

// Good
const adapter = openai({ apiKey: process.env.OPENAI_API_KEY! })

Validate at startup so the process fails fast:

function requireEnv(key: string): string {
  const v = process.env[key]
  if (!v) throw new Error(`Missing required env var: ${key}`)
  return v
}

const adapter = openai({ apiKey: requireEnv('OPENAI_API_KEY') })

#Vault integrations

Prefer fetching secrets at runtime from a vault rather than baking them into environment variables at build time.

#1Password SDK

import { createClient } from '@1password/sdk'

const client = await createClient({
  auth: process.env.OP_SERVICE_ACCOUNT_TOKEN!,
  integrationName: 'agentskit-agent',
  integrationVersion: '1.0.0',
})
const apiKey = await client.secrets.resolve('op://prod/openai/credential')

#HashiCorp Vault (KV v2)

const res = await fetch(
  `${process.env.VAULT_ADDR}/v1/secret/data/openai`,
  { headers: { 'X-Vault-Token': process.env.VAULT_TOKEN! } },
)
const { data } = (await res.json() as { data: { data: Record<string, string> } }).data
const apiKey = data.OPENAI_API_KEY

#Doppler

Doppler injects secrets as env vars at process start. No SDK required for server-side usage:

doppler run -- node dist/agent.js

For CI, use the Doppler GitHub Actions integration to inject secrets into the runner environment.

#Rotation

• Set short TTLs on all API keys (rotate every 30–90 days or on each deploy).
• Use vault dynamic secrets (Vault) or service accounts (1Password) where the credential is unique per process invocation.
• Invalidate and regenerate on suspected exposure; treat leaked keys as compromised immediately.

#Dev / prod separation

Never share credentials between environments:

OPENAI_API_KEY_DEV=sk-...
OPENAI_API_KEY=sk-...   # prod only, injected by vault / CI

• Use .env.local (git-ignored) for dev secrets.
• Never commit .env files containing real values.
• Add .env* to .gitignore and verify with git check-ignore -v .env.

#Secret detection in CI

Run a secret scanner on every commit:

# gitleaks
gitleaks detect --source . --redact

# trufflehog (OSS)
trufflehog git file://. --only-verified

Add the scanner as a pre-commit hook or CI step so exposure is caught before merge.

#Related

• PII redaction — strip sensitive data from agent messages and logs
• Observability — attach observers that receive agent events