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.

Provider	Value	Description
Environment Variables	env (default)	Reads from os.environ and .env files
AWS Secrets Manager	aws	Fetches from AWS Secrets Manager
GCP Secret Manager	gcp	Fetches 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:

Key	Purpose
SECRET_KEY	JWT signing key
SECRET_KEY_PREVIOUS	Previous signing key (for graceful rotation)
POSTGRES_PASSWORD	Database password
INSTANCE_ENCRYPTION_KEY	Fernet key for encrypting instance database URLs
CONTROL_PLANE_SECRET_KEY	Control-plane JWT signing key
SENDGRID_API_KEY	SendGrid email delivery
SCIM_BEARER_TOKEN	SCIM provisioning authentication
SMTP_PASSWORD	SMTP email delivery
STORAGE_S3_SECRET_KEY	S3 storage credentials
STORAGE_GCS_CREDENTIALS_JSON	GCS service account credentials
STORAGE_AZURE_CONNECTION_STRING	Azure 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.

Related

• Multi-Instance Architecture — How encrypted instance URLs are managed
• Source Systems — Connector credential storage