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

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 and use sync.

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
jwt_secret	Authentication	Token signing key (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
sync_token	Cloud sync	Sync authentication (optional)

JWT Secret Requirements

The JWT secret must be at least 32 characters. Generate a secure secret:

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

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 - Update secrets.json and run secrets sync
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
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.