​
Overview

Account-level secrets provide a secure way to manage sensitive configuration data such as API keys, tokens, passwords, and other credentials that your AI agents need across multiple Devboxes. Secrets are encrypted at rest and automatically made available as environment variables in your Devboxes.

​
Key Features

  • Encrypted at Rest: All secret values are encrypted using industry-standard encryption
  • Global Availability: Secrets are accessible across all Devboxes in your account
  • Environment Variables: Secrets are automatically injected as environment variables
  • Secure Access: Secret values are never exposed in logs or API responses after creation

​
Creating Secrets

Create a new secret with a globally unique name and value. The secret will be encrypted and made available as an environment variable in all your Devboxes.

curl -X POST \
  'https://api.runloop.ai/v1/secrets' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "SECRET_NAME",
    "value": "my-secure-secret-123"
  }'

​
Secret Naming Requirements

  • Must be a valid environment variable name
  • Alphanumeric characters and underscores only
  • Globally unique across your account
  • Examples: API_KEY, DATABASE_URL, JWT_SECRET

​
Listing Secrets

Retrieve all secrets in your account. For security reasons, secret values are not included in the response.

curl -X GET \
  'https://api.runloop.ai/v1/secrets' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY"

​
Updating Secrets

Update the value of an existing secret. The new value will be encrypted and replace the previous value.

curl -X POST \
  'https://api.runloop.ai/v1/secrets/SECRET_NAME' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "value": "my-updated-secret-456"
  }'

​
Deleting Secrets

Delete a secret permanently. This action is irreversible and will remove the secret from all Devboxes.

curl -X POST \
  'https://api.runloop.ai/v1/secrets/SECRET_NAME/delete' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{}'

Deleting a secret is permanent and cannot be undone. Any Devboxes relying on this secret will no longer have access to it.

​
Best Practices

​
Security Guidelines

  1. Use descriptive names: Choose clear, meaningful names for your secrets

    • ✅ STRIPE_SECRET_KEY
    • ❌ SECRET1

  2. Follow naming conventions: Use uppercase with underscores for consistency

    • ✅ DATABASE_URL
    • ❌ databaseUrl

  3. Rotate secrets regularly: Update secret values periodically for enhanced security

  4. Limit secret scope: Only store what’s necessary for your AI workflows

​
Operational Best Practices

  1. Document your secrets: Keep track of what each secret is used for
  2. Monitor secret usage: Regularly review which secrets are still needed
  3. Test after updates: Verify your Devboxes work correctly after updating secrets
  4. Clean up unused secrets: Delete secrets that are no longer needed

​
Common Use Cases

  • API Keys: Third-party service authentication

    OPENAI_API_KEY
ANTHROPIC_API_KEY
GITHUB_TOKEN

  • Database Credentials: Connection strings and passwords

    DATABASE_URL
REDIS_PASSWORD

  • Service Configuration: Application-specific settings

    JWT_SECRET
ENCRYPTION_KEY
WEBHOOK_SECRET