Store encrypted API keys and credentials.
Overview
Environment secrets are encrypted key-value pairs injected into your agent's runtime. Use them for API keys, tokens, and credentials you already have.
Adding a secret
- Go to Settings → Secrets
- Click Add Secret
- Enter a key (e.g.,
OPENAI_API_KEY) and value - Click Save
Your agents can now access it via environment variables:
python
1import os2api_key = os.environ["OPENAI_API_KEY"]Security
| Feature | Benefit |
|---|---|
| Encrypted at rest | AES-256-GCM encryption |
| Never logged | Not exposed in task outputs or logs |
| Team scoped | Other teams cannot access your secrets |
| Runtime only | Injected only when apps run, not stored in code |
| Selective injection | Only apps that declare the secret receive it |
Using in apps
Apps declare which secrets they need:
yaml
1requirements:2 secrets:3 - key: OPENAI_API_KEY4 description: For GPT-4 API calls5 6 - key: DATABASE_URL7 description: PostgreSQL connection string8 optional: trueRequired secrets must be set before the app can run.
Optional secrets won't block execution if missing.
Best practices
Use descriptive names
code
1✓ OPENAI_API_KEY2✓ STRIPE_SECRET_KEY3✓ AWS_ACCESS_KEY_ID4 5✗ KEY16✗ TOKEN7✗ SECRETDon't commit secrets
Never put secrets in:
- Version control
- App code
- Configuration files
Use the Secrets UI instead.
Rotate regularly
- Generate a new key in the external service
- Update the secret in Settings
- Revoke the old key
No app changes needed.
Use separate keys per environment
If you have staging and production:
- Use different API keys for each
- Set different secrets per team/environment
Common secrets
| Secret | Service | Description |
|---|---|---|
OPENAI_API_KEY | OpenAI | GPT-4, DALL-E, Whisper |
ANTHROPIC_API_KEY | Anthropic | Claude models |
REPLICATE_API_TOKEN | Replicate | ML model hosting |
HUGGINGFACE_TOKEN | Hugging Face | Model downloads |
AWS_ACCESS_KEY_ID | AWS | S3, Lambda, etc. |
AWS_SECRET_ACCESS_KEY | AWS | (paired with above) |
STRIPE_SECRET_KEY | Stripe | Payment processing |
SENDGRID_API_KEY | SendGrid | Email delivery |
TWILIO_AUTH_TOKEN | Twilio | SMS, voice |
Secrets vs Integrations
| Feature | Secrets | Integrations |
|---|---|---|
| Setup | You provide the key | OAuth flow or service account |
| Management | Manual rotation | Auto token refresh |
| Best for | APIs with static keys | OAuth services (Google, X.com) |
| Examples | OpenAI, Stripe, AWS | Gmail, Google Sheets, Twitter |
Use secrets when you have an API key.
Use integrations for OAuth services where we handle token management.
Troubleshooting
"Secret not found"
- Check the exact key name (case-sensitive)
- Verify the secret is set in Settings → Secrets
- Make sure the app declares the secret in requirements
"Permission denied"
- Secrets are team-scoped — you need access to the team
- Check you're logged into the correct team
App not receiving secret
- The app must declare the secret in
requirements.secrets - Only declared secrets are injected for security