Skip to main content

Secrets Management

Qarion uses a pluggable secrets management system to store and retrieve sensitive values like API keys, database credentials, and encryption keys. The system supports multiple provider backends and transparent encryption at rest.

Provider Backends​

Qarion resolves secrets through a configurable provider. The provider is selected via the SECRET_PROVIDER environment variable.

ProviderValueDescription
Environment Variablesenv (default)Reads from os.environ and .env files
AWS Secrets ManagerawsFetches from AWS Secrets Manager
GCP Secret ManagergcpFetches from Google Cloud Secret Manager
tip

The env provider works out of the box with .env files and Kubernetes Secret volumes. Cloud providers are loaded lazily — their SDKs are only imported when the provider is actually configured.

Environment Provider (Default)​

The default provider reads secrets from environment variables. It supports:

  • Literal keys — SECRET_KEY, SENDGRID_API_KEY
  • Slash-based refs — llm_api_key/control_plane resolves to LLM_API_KEY_CONTROL_PLANE

Cloud Providers​

For production deployments, use AWS Secrets Manager or GCP Secret Manager for centralized, auditable secret storage with automatic rotation capabilities.

Managed Secrets​

The following secrets are recognized by the platform:

KeyPurpose
SECRET_KEYJWT signing key
SECRET_KEY_PREVIOUSPrevious signing key (for graceful rotation)
POSTGRES_PASSWORDDatabase password
INSTANCE_ENCRYPTION_KEYFernet key for encrypting instance database URLs
CONTROL_PLANE_SECRET_KEYControl-plane JWT signing key
SENDGRID_API_KEYSendGrid email delivery
SCIM_BEARER_TOKENSCIM provisioning authentication
SMTP_PASSWORDSMTP email delivery
STORAGE_S3_SECRET_KEYS3 storage credentials
STORAGE_GCS_CREDENTIALS_JSONGCS service account credentials
STORAGE_AZURE_CONNECTION_STRINGAzure Blob Storage credentials
LLM_API_KEY_*AI model provider API keys

Encryption at Rest​

Instance Database URLs​

Instance connection URLs (containing database credentials) are encrypted at rest using Fernet symmetric encryption (AES-128-CBC + HMAC-SHA256). The encryption key is resolved from:

  1. INSTANCE_ENCRYPTION_KEY environment variable (recommended — must be a valid Fernet key)
  2. Fallback: A deterministic key derived from SECRET_KEY via SHA-256

The Instance model transparently encrypts on write and decrypts on read.

Connector Credentials​

Source system connector credentials are encrypted using AES-256 before storage. Encrypted values are never returned via API responses.

Key Rotation​

JWT Signing Keys​

To rotate the JWT signing key without invalidating active sessions:

  1. Copy the current SECRET_KEY to SECRET_KEY_PREVIOUS
  2. Set a new SECRET_KEY value
  3. Restart the application

Qarion validates tokens against both keys during the transition period.

Encryption Keys​

To rotate INSTANCE_ENCRYPTION_KEY:

  1. Set the new key value
  2. Run the re-encryption utility to update all stored ciphertexts
  3. Remove the old key

Runtime Rotation​

The env provider supports runtime rotation via os.environ updates, but these changes do not survive process restarts. For durable rotation, use a vault-backed cloud provider.