> ## Documentation Index
> Fetch the complete documentation index at: https://docs.julep.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets

> Securely store and manage sensitive information for your LLM applications

# 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:

<CodeGroup>
  ```python Python theme={"dark"}
  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}")
  ```

  ```bash CLI theme={"dark"}
  julep secrets create --name "openai_api_key" --value "sk-..." --description "OpenAI API key"
  ```

  ```bash API theme={"dark"}
  curl https://dev.julep.ai:443/api/secrets \
    --request POST \
    --header 'Content-Type: application/json' \
    --data '{
    "metadata": {},
    "name": "openai_api_key",
    "description": "",
    "value": "sk-..."
  }'
  ```
</CodeGroup>

#### 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:

```yaml theme={"dark"}
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:

```yaml theme={"dark"}
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

* [Using Secrets in Julep](/guides/using-secrets) - Step-by-step guide for using secrets
* [Secrets Management](/advanced/secrets-management) - Advanced guide for managing secrets
* [API Reference](/api-reference#tag/secrets) - Complete API reference for secrets