Secrets Management

The Radicalbit AI Gateway uses !secret KEY references in config.yaml to keep API keys and other sensitive values out of your configuration files. When the gateway loads a configuration that contains !secret OPENAI_API_KEY, it resolves the value from a configured secrets backend.

# config.yaml
credentials:
  api_key: !secret OPENAI_API_KEY

The gateway supports multiple backends for storing secrets:

• Local file — a secrets.yaml file mounted alongside your configuration
• Cloud secret managers — AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager, or Azure Key Vault via built-in plugins
• Custom plugins — implement your own secrets provider

---

Using secrets.yaml (Local File)

By default, the gateway reads secrets from a secrets.yaml file placed alongside config.yaml. The file is a flat mapping of secret names to values:

secrets.yaml

OPENAI_API_KEY: sk-proj-xxxxxxxxxxxxxxxx
GOOGLE_API_KEY: AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_API_KEY: sk-ant-xxxxxxxxxxxxxxxx
DEEPSEEK_API_KEY: your-deepseek-key

Reference these values in config.yaml with !secret:

config.yaml

chat_models:
  - model_id: gpt-4o
    model: openai/gpt-4o
    credentials:
      api_key: !secret OPENAI_API_KEY

The secrets.yaml file must be mounted into the container at /radicalbit_ai_gateway/secrets.yaml.

warning

Never commit secrets.yaml to version control. Add it to .gitignore.

---

Plugin-based Secrets Management

For production deployments, the gateway supports retrieving secrets from external secret managers via plugins. When a plugin is enabled, no secrets.yaml file is needed — the plugin replaces it entirely.

Plugins are enabled through the ENABLED_PLUGINS environment variable:

export ENABLED_PLUGINS="<plugin_name>"

All plugins share the same behavior:

• The secrets backend is read each time the gateway needs it: when it registers a project's routes (at startup and on every publish), when it validates the !secret references of a configuration, and on every request from the Secrets section. Nothing is cached between those reads, so a rotated secret value takes effect the next time the routes that use it are registered.
• If the backend cannot be read when the gateway registers a project's routes, the error is logged and that project is skipped. The other projects still start.
• The !secret KEY pattern in config.yaml works unchanged — the plugin is transparent to your configuration

Supported Providers

Provider	Plugin Name	Secret Model
AWS Secrets Manager	aws_secrets_manager	All secrets in one JSON object
HashiCorp Vault	hashicorp_vault	Key-value pairs under a single path
GCP Secret Manager	gcp_secret_manager	One secret per key (individual resources)
Azure Key Vault	azure_keyvault	One secret per key, prefix filtering available

Need to integrate with a different system? See Creating a Custom Secrets Plugin.

---

Seeing Your Secret Keys in the UI

The Secrets section of the gateway UI lists the secret keys the backend holds and the projects that use each one, so you can copy the exact key into a configuration. It never shows a secret value.

---

Next Steps

• Basic Configuration — Get started with a simple gateway setup
• Best Practices — Security and configuration best practices
• Advanced Configuration — Full configuration reference