Skip to main content
The Secrets page (Settings → Secrets) lets administrators store encrypted credentials—such as LLM provider API keys—directly in the Phoenix database. Stored secrets can be referenced by name in the playground and in custom AI provider configurations, eliminating the need for each user to paste keys into their browser.
The Secrets page is only visible to users with the Admin role. Non-admins are redirected to General Settings.

​
Prerequisites

Secrets are encrypted at rest using a key derived from the PHOENIX_SECRET environment variable. When PHOENIX_SECRET is not set, secrets are still stored but are encrypted with a deterministic fallback key that provides no real confidentiality. For production deployments, PHOENIX_SECRET must be set to ensure secrets are properly protected.

​
Managing Secrets in the UI

​
Creating a Secret

  1. Go to Settings → Secrets.
  2. Click New Secret.
  3. Enter a Key in environment-variable format (e.g., OPENAI_API_KEY). The key is automatically uppercased and spaces are replaced with underscores.
  4. Enter the Value. Values are write-only — the raw value cannot be retrieved after saving.
  5. Click Save.

​
Replacing a Secret Value

To update the value for an existing key, click Replace next to the secret and enter the new value. The key name cannot be changed; create a new secret and delete the old one if you need to rename a key.

​
Deleting a Secret

Click Delete next to the secret and confirm. Deleting a secret that is currently referenced by a custom AI provider or prompt configuration will cause those references to stop working.

​
Filtering Secrets

When authentication is enabled, you can switch between All secrets and My secrets using the owner filter at the top of the table.

​
Managing Secrets via the REST API

Administrators can also create, update, and delete secrets programmatically using the PUT /v1/secrets endpoint. A single request can upsert and delete multiple secrets atomically:
  • Entries with a non-null value are created or updated.
  • Entries with value: null are deleted.
When the same key appears more than once in a request, the last occurrence wins.

​
Example: Create or update secrets

curl -X PUT https://your-phoenix-host/v1/secrets \
  -H "Authorization: Bearer $PHOENIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "secrets": [
      { "key": "OPENAI_API_KEY", "value": "sk-..." },
      { "key": "ANTHROPIC_API_KEY", "value": "sk-ant-..." }
    ]
  }'

{
  "data": {
    "upserted_keys": ["OPENAI_API_KEY", "ANTHROPIC_API_KEY"],
    "deleted_keys": []
  }
}

​
Example: Delete a secret

curl -X PUT https://your-phoenix-host/v1/secrets \
  -H "Authorization: Bearer $PHOENIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "secrets": [
      { "key": "OLD_API_KEY", "value": null }
    ]
  }'
Deleting a key that does not exist succeeds silently.
Secret values are never returned in API responses. The REST API only reports which keys were upserted or deleted.

​
Security Considerations

  • Secret values are encrypted at rest using a key derived from PHOENIX_SECRET.
  • Only Admin users can create, update, or delete secrets via the UI or the REST API.
  • Values are write-only. Store a secure copy elsewhere before discarding the original value.
  • Deleting or rotating PHOENIX_SECRET will invalidate all stored secrets.

Custom AI Providers

Configure server-managed AI providers that can reference stored secrets

API Keys

Manage Phoenix API keys for authenticating requests