Secrets & Credentials

Sensitive configuration is stored in gitignored files within .systemprompt/. Secrets are encrypted at rest in cloud deployments and never exposed in logs or API responses.

Secrets in the Hierarchy

Secrets exist at the profile level. Each profile has its own secrets.json file containing credentials needed for that environment. This keeps development API keys separate from production keys.

The credential hierarchy flows: Cloud Login (user identity) → Tenant (isolation) → Profile (environment) → Secrets (credentials for that environment).

File Structure

.systemprompt/
├── credentials.json           # Cloud API credentials
├── tenants.json               # Tenant registry
└── profiles/
    └── local/
        └── secrets.json       # Profile-specific secrets

All these files are gitignored by default.

Profile Secrets

Each profile has a secrets.json:

// .systemprompt/profiles/local/secrets.json
{
  "database_url": "postgres://user:pass@localhost:5432/systemprompt",
  "anthropic_api_key": "sk-ant-...",
  "openai_api_key": "sk-...",
  "gemini_api_key": "AIza...",
  "github_token": "ghp_..."
}

Managing Secrets

List Secrets

systemprompt cloud secrets list

Output:

Secret                  Status      Last Updated
ANTHROPIC_API_KEY       Set         2026-01-30 10:30:00
OPENAI_API_KEY          Set         2026-01-30 10:30:00
DATABASE_URL            Set         2026-01-30 09:00:00
JWT_SECRET              Not Set     -

Set Secrets

# Set API key
systemprompt cloud secrets set ANTHROPIC_API_KEY "sk-ant-..."

# Set database URL
systemprompt cloud secrets set DATABASE_URL "postgres://user:pass@host:5432/db"

# Set multiple secrets
systemprompt cloud secrets set OPENAI_API_KEY "sk-..."
systemprompt cloud secrets set GEMINI_API_KEY "AIza..."

Unset Secrets

# Remove a secret
systemprompt cloud secrets unset GITHUB_TOKEN

# Remove with confirmation skip
systemprompt cloud secrets unset GITHUB_TOKEN -y

Required Secrets

Secret	Required For	Description
ANTHROPIC_API_KEY	AI providers	Claude API access
OPENAI_API_KEY	AI providers	OpenAI API access
GEMINI_API_KEY	AI providers	Google Gemini access
DATABASE_URL	Database	PostgreSQL connection (auto-configured for cloud)
JWT_SECRET	Authentication	Token signing (auto-generated)
GITHUB_TOKEN	Integrations	GitHub API access

Environment-Specific Secrets

Secrets are scoped to profiles. Each profile can have different values:

# Set secret for production profile
systemprompt cloud secrets set ANTHROPIC_API_KEY "sk-ant-prod-..." --profile production

# Set secret for staging profile
systemprompt cloud secrets set ANTHROPIC_API_KEY "sk-ant-staging-..." --profile staging

Syncing Secrets to Cloud

Push local secrets to cloud deployment:

# Sync all secrets to cloud
systemprompt cloud secrets sync

# Sync specific secret
systemprompt cloud secrets sync ANTHROPIC_API_KEY

Pull cloud secrets to local:

# Pull secrets from cloud (requires confirmation)
systemprompt cloud secrets pull

Rotating Credentials

Rotate secrets without downtime:

# Rotate a secret (sets new value, keeps old active briefly)
systemprompt cloud secrets rotate ANTHROPIC_API_KEY "sk-ant-new-..."

# Force immediate rotation
systemprompt cloud secrets rotate ANTHROPIC_API_KEY "sk-ant-new-..." --immediate

Cloud Credentials

// .systemprompt/credentials.json
{
  "api_token": "sp_token_...",
  "api_endpoint": "https://api.systemprompt.io",
  "user_email": "user@example.com",
  "authenticated_at": "2026-01-30T00:00:00Z"
}

Generated by systemprompt cloud auth login.

Tenant Registry

// .systemprompt/tenants.json
{
  "tenants": [
    {
      "id": "local_abc123",
      "name": "my-project",
      "tenant_type": "local",
      "database_url": "postgres://localhost:5432/local_abc123"
    },
    {
      "id": "tenant_def456",
      "name": "production",
      "tenant_type": "cloud",
      "hostname": "tenant_def456.systemprompt.cloud",
      "region": "iad"
    }
  ],
  "active_tenant": "local_abc123"
}

Environment Variables

Secrets can also be set via environment variables:

# In .env file
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GEMINI_API_KEY=AIza...

# Or export directly
export ANTHROPIC_API_KEY=sk-ant-...

Service configs reference them with ${VAR_NAME} syntax:

# services/ai/config.yaml
providers:
  anthropic:
    api_key: ${ANTHROPIC_API_KEY}
  openai:
    api_key: ${OPENAI_API_KEY}

Security Best Practices

1. Never commit secrets - All secret files are gitignored
2. Use separate secrets per environment - Different keys for staging vs production
3. Rotate regularly - Use secrets rotate for periodic rotation
4. Least privilege - Only set secrets that are actually needed
5. Audit access - Check systemprompt cloud secrets audit for access logs
6. Use environment variables in CI/CD

Troubleshooting

Issue	Cause	Solution
Secret not found	Not synced to cloud	Run systemprompt cloud secrets sync
Permission denied	Insufficient role	Contact tenant admin
Sync failed	Network error	Check connection, retry
Invalid value	Format error	Verify secret format

Quick Reference

Task	Command
Set secret	systemprompt cloud secrets set <KEY> <VALUE>
List secrets	systemprompt cloud secrets list
Remove secret	systemprompt cloud secrets unset <KEY>
Sync to cloud	systemprompt cloud secrets sync
Pull from cloud	systemprompt cloud secrets pull
Rotate secret	systemprompt cloud secrets rotate <KEY> <VALUE>