Secrets Management

This guide covers advanced topics for managing secrets in Julep, including security architecture, best practices, rotation policies, and integration patterns.

Security Architecture

Secrets in Julep are stored with a layered security approach:

Application-level Validation: Secrets are validated before being stored
Database Encryption: Secrets are stored encrypted using PostgreSQL’s pgcrypto extension with AES-256
Access Control: Secrets are scoped to developers and only accessible within their resources
Master Key Security: A separate master encryption key secures all stored secrets

The encryption process works as follows:

When a secret is created, its value is encrypted using the master key
The encrypted value is stored in the database’s value_encrypted column
When a secret is accessed, the value is decrypted using the master key
The master key is stored as an environment variable, separate from the database

Creating Effective Secret Names

Secrets should have descriptive names that follow these conventions:

Use snake_case formatting
Begin with a letter and contain only alphanumeric characters and underscores
Use a prefix to indicate the service (e.g., aws_secret_key, stripe_api_key)
Be specific enough to understand the purpose (e.g., gmail_oauth_token vs email_token)

Secret Rotation Best Practices

Regular rotation of secrets is a security best practice:

Create a new secret with a temporary name
Update your services to use the new secret
Once confirmed working, delete the old secret
Update the new secret’s name to the standard name

For automated rotation:

from julep import Julep
import uuid

client = Julep(api_key="your_api_key")

# Generate temporary name
temp_name = f"stripe_key_rotation_{uuid.uuid4().hex[:8]}"

# Create new secret with temp name
client.secrets.create(
    name=temp_name,
    value="sk_new_value...",
    description="New Stripe API key (rotation)",
    metadata={"rotation_date": "2025-05-10"}
)

# Test the new key (implement your validation logic here)
# ...

# If valid, delete old secret and rename new one
client.secrets.delete(name="stripe_api_key")
client.secrets.update(
    name=temp_name,
    new_name="stripe_api_key",
    description="Stripe API key",
    metadata={"last_rotated": "2025-05-10"}
)

Using Secrets with Different Tool Types

API Tools

For HTTP-based tools, reference secrets in the headers or authentication:

steps:
  - kind: tool_call
    tool: api_service
    operation: fetch_data
    arguments:
      url: "https://api.example.com/data"
      headers:
        Authorization: "$ f'Bearer {secrets.api_token}'"

Database Connections

For database tools, use secrets for connection credentials:

steps:
  - kind: tool_call
    tool: database
    operation: query
    arguments:
      query: "SELECT * FROM users LIMIT 10"
    secrets:
      db_username: "my_db_user"
      db_password: "my_db_password"

AI Service Integration

For AI services that require API keys:

steps:
  - kind: prompt
    model: "$ secrets.preferred_model"
    provider: "$ secrets.provider_name"
    prompt: "Generate creative ideas for a marketing campaign"
    api_key: "$ secrets.openai_api_key"

Managing Secrets for Multi-Environment Deployments

For applications deployed across development, staging, and production environments:

Use consistent naming conventions with environment prefixes:
- dev_stripe_key, staging_stripe_key, prod_stripe_key

Use metadata to tag secrets by environment:

client.secrets.create(
    name="stripe_api_key",
    value="sk_test_...",
    metadata={"environment": "production"}
)

Filter secrets by environment when listing:

prod_secrets = client.secrets.list(
    metadata={"environment": "production"}
)

Secret Templating

For complex configurations that require multiple secrets:

steps:
  - kind: tool_call
    tool: database
    operation: query
    arguments:
      connection_string: "$ f'mongodb+srv://{secrets.db_username}:{secrets.db_password}@{secrets.db_host}/{secrets.db_name}'"

Securing LLM API Keys with Secrets

Julep automatically looks for LLM API keys in your secrets store based on the provider name. Use these naming conventions for automatic lookup:

Provider	Secret Name
OpenAI	`OPENAI_API_KEY`
Anthropic	`ANTHROPIC_API_KEY`
Google	`GOOGLE_API_KEY`
Azure OpenAI	`AZURE_OPENAI_API_KEY`
Cohere	`COHERE_API_KEY`

Example of setting up an LLM API key:

client.secrets.create(
    name="OPENAI_API_KEY",
    value="sk-...",
    description="OpenAI API key for GPT-4 access"
)

Audit and Monitoring

Best practices for security monitoring:

Regularly audit secret access and usage
Track changes to secrets via the updated_at timestamp
Implement secret expiration for highly sensitive data
Use metadata to track last review or rotation dates

Example audit script:

from julep import Julep
from datetime import datetime, timedelta

client = Julep(api_key="your_api_key")

# Find secrets not rotated in over 90 days
old_threshold = datetime.now() - timedelta(days=90)
secrets = client.secrets.list()

for secret in secrets.items:
    if secret.updated_at < old_threshold:
        print(f"WARNING: Secret {secret.name} has not been rotated in over 90 days")

Troubleshooting

Common issues when working with secrets:

Secret Not Found: Check that the secret name matches exactly, including case
Permission Errors: Verify the developer ID has access to the secret
Encryption Errors: Ensure the master key is correctly set in the environment
Reference Errors: Ensure the secret reference syntax is correct in expressions and templates

Next Steps

Using Secrets in Julep - Step-by-step guide for using secrets
Integration Patterns - Learn how to use secrets with integrations
API Reference - Complete API reference for secrets

​Secrets Management

​Security Architecture

​Creating Effective Secret Names

​Secret Rotation Best Practices

​Using Secrets with Different Tool Types

​API Tools

​Database Connections

​AI Service Integration

​Managing Secrets for Multi-Environment Deployments

​Secret Templating

​Securing LLM API Keys with Secrets

​Audit and Monitoring

​Troubleshooting

​Next Steps