Secrets

Encrypted key-value storage with environment inheritance and variable references.

What It Does

• AES-256-GCM encryption at rest
• Environment inheritance (child environments get parent values)
• Variable references: DATABASE_URL='postgres://${HOST}:${PORT}/db'
• History tracking (created, updated, deleted)
• Export formats: shell, JSON, YAML, .env

Usage

# Set a secret
soup secrets set API_KEY xyz

# Get a secret
soup secrets get API_KEY

# List all secrets
soup secrets list

# Run command with secrets injected
soup run -- npm start

Context (project/environment) auto-selected from soup config.

Inheritance

Environments can have a parent. Child gets all parent secrets unless overridden.

root
├── development (inherits from root)
└── production (inherits from root)

Set in root, override in production:

soup secrets set --env root DATABASE_HOST localhost
soup secrets set --env production DATABASE_HOST prod-db.internal

Production gets DATABASE_HOST=prod-db.internal, everything else from root.

Variable References

Reference other secrets with ${VAR}:

soup secrets set DB_HOST localhost
soup secrets set DB_PORT 5432
soup secrets set DATABASE_URL 'postgres://${DB_HOST}:${DB_PORT}/db'

Resolved at export time. Change DB_HOST, DATABASE_URL updates automatically.

Encryption

• Algorithm: AES-256-GCM
• Key: 32-byte key from SOUP_ENCRYPTION_KEY env var or generated at startup
• Storage: 12-byte nonce prepended to ciphertext
• Decryption: On-demand when accessed via API/CLI

History

Every change tracked in secret_history table:

• Action: created, updated, deleted
• Who made the change (user_id)
• When it happened (created_at)
• Previous value (for updates/deletes)

Retrieve via API: GET /projects/{slug}/environments/{env}/secrets/{key}/history

API

GET    /api/v1/projects/{slug}/environments/{env}/secrets
POST   /api/v1/projects/{slug}/environments/{env}/secrets
GET    /api/v1/projects/{slug}/environments/{env}/secrets/{key}
DELETE /api/v1/projects/{slug}/environments/{env}/secrets/{key}

See API Reference for details.

Limits

• Personal (Free): Unlimited secrets
• Starter ($5/user): Unlimited secrets

No secret size limit enforced (reasonable values recommended).