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
{
  "oauth_at_rest_pepper": "generated-during-setup...",
  "database_url": "postgres://user:pass@localhost:5432/systemprompt",
  "anthropic": "sk-ant-...",
  "openai": "sk-...",
  "gemini": "AIza...",
  "github": "ghp_..."
}

Managing Secrets

View Secrets

Secrets are stored in profile-specific secrets.json files:

# View secrets file
cat .systemprompt/profiles/local/secrets.json

Sync Secrets to Cloud

# Sync all secrets from secrets.json to cloud
systemprompt cloud secrets sync

Set Secrets

# Set secret (KEY=VALUE format, no spaces around =)
systemprompt cloud secrets set ANTHROPIC_API_KEY=sk-ant-...

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

Note: set directly updates cloud secrets. For local development, edit secrets.json directly or use systemprompt admin config secret set, then sync when you deploy.

Unset Secrets

# Remove a secret
systemprompt cloud secrets unset GITHUB_TOKEN

# Remove multiple secrets
systemprompt cloud secrets unset GITHUB_TOKEN OPENAI_API_KEY

Required Secrets

Secret	Required For	Description
oauth_at_rest_pepper	Authentication	At-rest encryption pepper (minimum 32 characters)
database_url	Database	PostgreSQL connection string
anthropic	AI providers	Anthropic Claude API key
openai	AI providers	OpenAI API key
gemini	AI providers	Google Gemini API key
github	Integrations	GitHub personal access token

Pepper Requirements

The oauth_at_rest_pepper must be at least 32 characters. just setup-local generates one automatically; to create one manually:

openssl rand -base64 48

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 from secrets.json to cloud
systemprompt cloud secrets sync

Rotating Credentials

To rotate a secret:

1. Update the value in secrets.json
2. Run systemprompt cloud secrets sync to push the new value
3. Restart any services using that secret

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-...

Environment variables are read at bootstrap and fill any provider key missing from secrets.json. The lookup names match the table above (ANTHROPIC_API_KEY maps to anthropic, and so on).

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 - Update secrets.json and run secrets sync
4. Least privilege - Only set secrets that are actually needed
5. Audit access - Every AI request is logged; review with systemprompt infra logs request list
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
Set multiple	systemprompt cloud secrets set K1=V1 K2=V2
Remove secret	systemprompt cloud secrets unset KEY
Sync to cloud	systemprompt cloud secrets sync
Cleanup system vars	systemprompt cloud secrets cleanup

Note: View secrets by reading .systemprompt/profiles/<profile>/secrets.json directly.