​
Secrets

Secrets allow you to securely store and manage sensitive information like API keys, credentials, and other confidential data that your agents and tasks need to access external services.

​
What are Secrets?

Secrets are encrypted key-value pairs that can be referenced in your tasks and used by your agents without exposing the actual values in your code or configuration files. This helps maintain security and separates sensitive data from your application logic.

​
Key Features

  • Encrypted Storage: All secrets are encrypted at rest using industry-standard AES-256 encryption
  • Access Control: Secrets are scoped to developers and cannot be accessed across developer accounts
  • Named References: Reference secrets by name in tasks and tools instead of hardcoding values
  • Versioning: Track when secrets were created and updated
  • Metadata Support: Add custom metadata to organize and categorize your secrets

​
Common Use Cases

  • Storing API keys for external services (OpenAI, Google, AWS, etc.)
  • Managing database credentials
  • Securing authentication tokens
  • Storing sensitive configuration values
  • Managing encrypted communication channels

​
Secrets vs. Environment Variables

While environment variables are commonly used for configuration, secrets provide several advantages:

  • Encrypted Storage: Environment variables are stored in plain text, while secrets are encrypted
  • Access Management: Environment variables are global, while secrets have access controls
  • Audit Trail: Secrets maintain creation and update timestamps
  • Organized Management: The secrets API provides a structured way to manage sensitive data

​
Working with Secrets

​
Creating Secrets

Secrets can be created through the API, SDK, or CLI:

secret = client.secrets.create(
name="stripe_api_key",
value="sk_test_...",
description="Stripe API key for payment processing",
metadata={"environment": "production", "owner": "payments-team"}
)

print(f"Created secret: {secret.name}")

​
Required Parameters

  • name: The name of the secret (must be a valid identifier)
  • value: The secret value to encrypt and store

​
Optional Parameters

  • description: A description of what the secret is used for
  • metadata: A dictionary of metadata to associate with the secret

​
Using Secrets in Tasks

Once created, secrets can be referenced in your tasks:

steps:
  - kind: tool_call
    tool: openai
    operation: completion
    arguments:
      prompt: "Summarize this text"
    secret_name: openai_api_key

​
Using Secrets in Expressions

You can also reference secrets in expressions:

steps:
  - kind: prompt
    model: gpt-4
    prompt: "Generate a summary"
    template_variables:
      api_url: "$ f'https://api.example.com/v1?key={secrets.api_key}'"

​
Secret Names and Conventions

Secret names must:

  • Begin with a letter
  • Contain only alphanumeric characters and underscores
  • Be unique within a developer account

Good naming conventions:

  • Use descriptive names like stripe_api_key instead of just api_key
  • Include service names in the key name
  • Use consistent formatting (snake_case recommended)

​
Next Steps