Skip to main content
ModuleX stores the secrets you trust it with — integration access tokens, API keys, OAuth client secrets — encrypted at rest, and never returns them in plaintext once written. Each credential is protected with its own key, and your ModuleX API keys are kept only as one-way fingerprints that can be verified but never read back. This page explains what ModuleX protects, how those protections work at a high level, and the production safeguards that keep the underlying keys strong. For how credentials are modelled, resolved at run time, and exposed through the credentials API, see Credentials & OAuth2. For the two authentication paths into ModuleX, see Auth model: JWT vs API key.
The operator-facing settings on this page — the master secrets, the managed key vault, and the production startup checks — apply to self-hosted and managed deployments. On the hosted ModuleX service these are handled for you, and you never set them yourself.

​
What ModuleX protects

Connected credentials

Access tokens, API keys, and OAuth settings for the services you connect are encrypted before they are stored, and decrypted only in memory at the moment of use.

OAuth app secrets

The secrets behind ModuleX’s managed OAuth apps — the ones that let you connect a service without registering your own OAuth application — are protected with their own separately-keyed encryption.

Your ModuleX API keys

API keys are never stored. ModuleX keeps a one-way fingerprint, shows you the full key once, and can verify it later without ever holding the original.

​
Per-credential isolation

Every credential is sealed with a key that is unique to that credential in that organization. Because the key is bound to both the organization and the specific credential, a stored secret cannot be unlocked outside the organization it belongs to — and a leaked record on its own is not enough to read a secret, because the master key is required as well.

​
API keys are one-way

When you create a ModuleX API key, ModuleX generates it from strong randomness, shows it to you once, and keeps only a one-way fingerprint hardened with a server-side secret that lives outside the database. On every request the presented key is checked against that fingerprint in a way that resists timing attacks. Because the original is never stored, a key cannot be shown again after creation — if one leaks, revoke it and issue a new one. For the key format and how keys authenticate requests, see Authentication.

​
Secrets are never returned in plaintext

Once a credential is saved, ModuleX never returns its secret. List and detail responses show a masked value — only the first and last few characters, for example start***end — and OAuth2 credentials report a literal OAuth2 label rather than any token. ModuleX also redacts sensitive fields such as passwords, tokens, and API keys from application logs, so there is no API or log path that emits a stored secret in full.

​
Key management

The encryption that protects your credentials depends on two master secrets. On self-hosted and managed deployments, these resolve from your environment first, then a managed key vault — so you can keep them out of source control and in the secret store you already trust.
​
string
required
The master key behind all credential encryption.
  • Minimum length: 32 characters.
  • Production / staging: required (see the production safeguards below).
  • Generate: python3 -c "import secrets; print(secrets.token_urlsafe(32))"
Treat ENCRYPTION_KEY as permanent for the life of your data — it is the key that unlocks every stored credential, so keep it stable and store it safely.
​
string
required
The server-side secret that hardens the one-way fingerprints of your ModuleX API keys.
  • Minimum length: 32 characters.
  • Production / staging: required.
  • Generate: python3 -c "import secrets; print(secrets.token_hex(32))"
Like ENCRYPTION_KEY, set API_KEY_PEPPER once, keep it stable, and set it explicitly when you self-host.

​
Sourcing secrets from a key vault

When AZURE_KEY_VAULT_URL is set, ModuleX sources its master secrets from Azure Key Vault instead of reading them from the environment. The client authenticates with a managed identity, so there is no secret-to-fetch-secrets bootstrap problem. Secrets are read once at startup, so plan rotations around a restart.
​
string
The Key Vault URL (for example https://my-vault.vault.azure.net/). Setting it enables vault sourcing; leaving it unset means ModuleX reads from environment variables only — the default for local development.

​
Production safeguards

ModuleX validates its security configuration at startup. In production and staging, a missing or weak ENCRYPTION_KEY or API_KEY_PEPPER stops the backend from starting at all — there is no degraded mode, so a misconfigured deployment refuses to serve traffic rather than run with weak keys. When the checks pass, the backend continues normally.
​
string
default:"development"
The deployment environment. production and staging turn on the strict startup checks above.
If a deployment exits immediately at startup with a security-validation message, set ENCRYPTION_KEY and API_KEY_PEPPER to strong 32+ character values (or wire up a key vault) and restart. Do not switch ENVIRONMENT away from production to get past it — that turns off the protection that keeps your stored secrets safe.

​
Compliance

For ModuleX’s compliance posture, certifications, and the list of sub-processors, see Compliance and Sub-processors.

Credentials & OAuth2

How credentials are modelled, resolved at run time, and exposed through the credentials API — including the OAuth2 PKCE flow.

Auth model: JWT vs API key

The two authentication paths into ModuleX and the headers each request must carry.

Security overview

How ModuleX secures your data, credentials, and access across the platform.

Deployment & SSO

Single sign-on and self-hosted or managed deployment options for enterprise.