Skip to main content

Configuring Secret Providers

Version: 0.1.0

Secrets store per-project credentials like LLM API keys and warehouse service account keys. DecisionBox supports three secret backends.

Provider Comparison​

ProviderBest ForEncryptionDependencies
MongoDB (default)Local dev, single-serverAES-256-GCMNone (uses existing MongoDB)
GCP Secret ManagerGCP productionGoogle-managedGCP project + IAM
AWS Secrets ManagerAWS productionAWS-managedAWS account + IAM

MongoDB Provider (Default)​

Uses an encrypted MongoDB collection. No external service needed — it reuses your existing MongoDB.

Setup​

# Generate encryption key
export SECRET_ENCRYPTION_KEY=$(openssl rand -base64 32)

# Set env vars (docker-compose or shell)
SECRET_PROVIDER=mongodb
SECRET_NAMESPACE=decisionbox
SECRET_ENCRYPTION_KEY=your-base64-key

How It Works​

  • Secrets stored in the secrets MongoDB collection
  • Each secret encrypted with AES-256-GCM using the encryption key
  • Random nonce per encryption (same plaintext → different ciphertext)
  • Unique index on (namespace, project_id, key) prevents duplicates

Without Encryption Key​

If SECRET_ENCRYPTION_KEY is not set, secrets are stored in plaintext with a warning in the logs. This is acceptable for local development but not for production.

Secret Format​

MongoDB stores:

{
  "namespace": "decisionbox",
  "project_id": "507f1f77bcf86cd799439011",
  "key": "llm-api-key",
  "value": "<encrypted-base64>",
  "nonce": "<base64-nonce>",
  "updated_at": "2026-03-14T10:00:00Z"
}

GCP Secret Manager​

Uses Google Cloud Secret Manager for production GCP deployments.

Setup​

SECRET_PROVIDER=gcp
SECRET_GCP_PROJECT_ID=my-gcp-project
SECRET_NAMESPACE=decisionbox

Prerequisites​

  • GCP project with Secret Manager API enabled
  • Service account or ADC with:
    • secretmanager.secrets.create
    • secretmanager.secrets.list
    • secretmanager.versions.add
    • secretmanager.versions.access

How It Works​

  • Secrets stored as GCP Secret Manager secrets
  • Naming: {namespace}-{projectID}-{key} (e.g., decisionbox-507f1f-llm-api-key)
  • Labels: managed-by=decisionbox, namespace=..., project-id=...
  • Listing filtered by labels (only shows DecisionBox-managed secrets)
  • New values added as new secret versions

Authentication​

On GKE: Uses Workload Identity automatically. Outside GCP: Uses Application Default Credentials (gcloud auth application-default login).

AWS Secrets Manager​

Uses AWS Secrets Manager for production AWS deployments.

Setup​

SECRET_PROVIDER=aws
SECRET_AWS_REGION=us-east-1
SECRET_NAMESPACE=decisionbox

Prerequisites​

  • AWS account with Secrets Manager access
  • IAM permissions:
    • secretsmanager:CreateSecret
    • secretsmanager:GetSecretValue
    • secretsmanager:PutSecretValue
    • secretsmanager:ListSecrets

How It Works​

  • Secrets stored as AWS Secrets Manager secrets
  • Naming: {namespace}/{projectID}/{key} (e.g., decisionbox/507f1f/llm-api-key)
  • Tags: managed-by=decisionbox, namespace=..., project-id=...
  • Listing filtered by name prefix and tags
  • Updates use PutSecretValue (creates new version)

Authentication​

On EKS: Uses IAM role for service accounts (IRSA) automatically. Outside AWS: Uses ~/.aws/credentials or environment variables.

Using Secrets​

Setting Secrets (Dashboard)​

  1. Go to project Settings → Secrets tab
  2. Select key from dropdown:
    • LLM API Key — Your LLM provider's API key
    • Warehouse Credentials (SA Key JSON) — Service account JSON for cross-cloud warehouse access
  3. Enter the value and click Save Secret

Setting Secrets (API)​

curl -X PUT http://localhost:8080/api/v1/projects/{id}/secrets/llm-api-key \
  -H "Content-Type: application/json" \
  -d '{"value": "sk-ant-api03-..."}'

How the Agent Reads Secrets​

  1. Agent initializes the secret provider (same config as API)
  2. Reads llm-api-key for the project → passes to LLM provider
  3. Reads warehouse-credentials (if set) → passes to warehouse provider
  4. If warehouse-credentials is not set, falls back to local cloud credentials (ADC, IAM role)

No Delete Via API​

Secrets cannot be deleted through the DecisionBox API. This is intentional — to prevent accidental deletion. To remove a secret:

  • MongoDB provider: Delete from the secrets collection directly
  • GCP provider: Delete via GCP Console or gcloud secrets delete
  • AWS provider: Delete via AWS Console or aws secretsmanager delete-secret

Namespace Isolation​

The SECRET_NAMESPACE prevents conflicts when multiple DecisionBox instances share the same secret backend:

Instance 1: SECRET_NAMESPACE=decisionbox-prod
Instance 2: SECRET_NAMESPACE=decisionbox-staging

Each instance only sees and manages its own secrets.

Next Steps​