Secrets

Securely inject API keys, tokens, and credentials into agent sandboxes. Secrets are encrypted at rest, scoped to sessions, and never exposed in logs.

How secrets work

Secrets are per-session key-value pairs that get injected as environment variables into the agent sandbox. They're encrypted with AES-256-GCM using per-platform derived keys (HKDF), and are never logged or returned in API responses.

set-secrets.ts

import { Theazo } from class="cb-str">'theazo'

const theazo = new Theazo({ apiKey: class="cb-str">'th_live_...' })
const session = await theazo.sessions.forUser(class="cb-str">'user_123')

// Set secrets for this session
await session.secrets.set({
  OPENAI_API_KEY: class="cb-str">'sk-...',
  STRIPE_SECRET:  class="cb-str">'sk_live_...',
  DATABASE_URL:   class="cb-str">'postgres://user:pass@host:5432/db'er:pass@host:5432/db',
})

// Agents in this session can access these as env vars
const agent = await session.agents.create({
  compute: class="cb-str">'python',
  secrets: [class="cb-str">'OPENAI_API_KEY', class="cb-str">'STRIPE_SECRET', class="cb-str">'DATABASE_URL'],
})

// Inside the sandbox:
// process.env.OPENAI_API_KEY → 'sk-...'
// process.env.STRIPE_SECRET  → 'sk_live_...'

Secrets are only injected into agent sandboxes that explicitly request them via the secrets array in agent create options. An agent cannot access secrets it didn't declare.

Listing secrets

List secret names for a session. Values are never returned — only metadata.

const secrets = await session.secrets.list()

// secrets = [
//   { name: 'OPENAI_API_KEY',  createdAt: '2025-05-01T10:00:00Z' },
//   { name: 'STRIPE_SECRET',   createdAt: '2025-05-01T10:00:00Z' },
//   { name: 'DATABASE_URL',    createdAt: '2025-05-01T10:00:00Z' },
// ]

Updating secrets

Call secrets.set() again to update existing secrets or add new ones. Running agents are not affected — they use the value from when their sandbox was created.

// Update an existing secret
await session.secrets.set({
  OPENAI_API_KEY: class="cb-str">'sk-new-key-...',
})

// The old value is overwritten. New agents get the new value.
// Running agents still have the old value in their sandbox.

Deleting secrets

await session.secrets.delete(class="cb-str">'OPENAI_API_KEY')
// Secret is permanently removed
// Agents that declared it will fail if they try to access it

Security model

Encrypted at rest — AES-256-GCM with per-platform keys derived via HKDF
Never logged — Secret values are excluded from all logs, traces, and API responses
Session-scoped — Secrets are isolated to the session that created them
Explicit access — Agents must declare which secrets they need at creation time
Env injection — Secrets are set as environment variables in the sandbox, not passed as arguments

Never pass secrets as task input or agent instructions. Always use the secrets API so values are encrypted and not visible in logs.

API reference

session.secrets.set(kv)Promise<void>Set one or more secrets as key-value pairs. Overwrites existing keys.

session.secrets.list()Promise<SecretInfo[]>List secret names and creation timestamps. Values are never returned.

session.secrets.delete(name)Promise<void>Delete a secret by name.

REST endpoints

POST/v1/sessions/:sid/secretsSet secrets (body: key-value object)

GET/v1/sessions/:sid/secretsList secret names (values not returned)

DELETE/v1/sessions/:sid/secrets/:nameDelete a secret