What data is processed, which fields support encryption, and how system vs organization scopes apply.

Data Processing & Encryption

This page explains:

which data categories the platform processes,
which scope (system vs organization DEK) applies,
representative fields that use FieldEncrypted when encryption is enabled for that scope,
and which KMS providers the Admin UI supports.

How scopes map to data

Encryption is not one global switch for all MongoDB data. The application attaches an encryption scope to each operation:

System scope: Used when handling platform and configuration documents, including admin User records, organization profile fields, payment provider configuration, site labels, and saved organization/site SMTP or geolocation secrets. Requires System > Encryption to be configured and enabled with an active system DEK.
Organization scope: Used for tenant runtime/customer documents such as clients, checkout sessions, transactions, invoices, credit notes, and queued notification payloads. Requires Settings > Encryption for that organization to be configured and enabled with an active organization DEK.

If encryption is disabled or no active DEK exists for a scope, affected FieldEncrypted fields remain in plaintext for that scope.

Stack coverage: Configuration and DEK management are performed in the Admin UI (admin backend). The main (checkout) API and workers read and write the same MongoDB documents; when organization encryption is enabled, they use the same organization DEK (unwrap via KMS) for tenant-scoped FieldEncrypted fields. Operate all of these processes with equivalent access to KMS and consistent deployment configuration.

Data categories processed

Category	Typical examples	DEK scope when field encryption is active
Platform admin users	Email, display name, mobile phone	System
Tenant configuration records	Organization profile fields, payment provider configuration, site labels, saved organization/site SMTP and geolocation secrets	System
Tenant runtime/customer data	Clients, saved addresses, checkout sessions, transactions, invoices, credit notes	Organization
Notifications (queued)	Email/SMS recipient channels, invoice template party lines, denormalized customer email	Organization (documents are tied to `organizationId`)
System notification settings	Platform portal SMTP settings in the singleton system document	System

The exact records depend on enabled modules and configuration.

Representative encrypted fields

The following lists are representative of types defined in the shared and backend type packages. They are encrypted only when the correct scope has encryption enabled and an active DEK. Fields omitted here may still be added over time; treat this as a guide for evaluations and DPIAs.

Address-like values (`Address` / embedded billing & shipping)

Encrypted: company name, first and last name, address lines, city, state, postcode, phone, VAT/tax id, email.

Not encrypted as FieldEncrypted: ISO 3166-1 alpha-2 country code (stored as a normal string for validation and routing).

Clients

Encrypted: email, first/last name, company name, phone, tax id (in tax info). Billing and shipping addresses use the address rules above.

Transactions

Encrypted: customer email, return URL, IP address (when present), IPN URL. Other fields (amount, currency, status, provider response blobs, etc.) are not FieldEncrypted in the transaction document itself; line items and addresses use encrypted types where modeled.

Invoices (including portal-facing party blocks)

Encrypted: seller/buyer name, email, VAT id, phone, address lines, city, state, postal code. Country remains a plaintext country code on party objects where applicable.

Payment providers and tenant configuration

The provider configuration payload (secrets and provider-specific JSON) is stored as FieldEncrypted under the system encryption scope. Organization profile fields, site labels, and saved organization/site SMTP or geolocation provider secrets are also configuration data protected by the system scope.

Admin users (admin backend)

Encrypted: email, name, mobile phone.

Email and SMS notification jobs

Email notifications: recipient email, denormalized customer email, seller/buyer lines used in templates, etc. SMS notifications: subscriber phone number as FieldEncrypted.

Optional searchable fields

Some fields (for example client email) may store a search hash alongside ciphertext to support lookup without indexing plaintext.

Existing data and background jobs

Turning encryption on for a scope affects new writes immediately once a DEK is active. Older documents may still hold plaintext inside FieldEncrypted until they are updated or processed by a bulk encryption job started from the Admin UI encryption pages.

Similarly, full DEK rotation (as opposed to envelope re-wrap) can start a background re-encryption pass so ciphertext is bound to the new DEK version. Disabling encryption or running decryption may use the same style of job. Monitor progress and errors in the encryption UI when running these operations on large datasets.

Context-bound encrypted fields

Application encrypted fields use authenticated encryption. Ciphertext is bound to its encryption context, including the scope, organization, collection, field, and DEK version. Do not copy encrypted field metadata from one document shape to another. For example, an encrypted invoices.client.name value must not be copied into credit_notes.client.name; the target field must be written from plaintext so it is encrypted under the credit-note context.

This is especially important for legal document snapshots. Invoices and credit notes may copy seller and client snapshot values for accounting consistency, but the copy must be plaintext-only before persistence. If encrypted metadata is moved between contexts, reads can fail with message authentication failed and the original plaintext cannot be recovered from that ciphertext alone.

For customer environments, diagnose these failures from admin-backend and worker logs plus the affected Admin UI page. Look for message authentication failed and field-level decrypt errors; the log context identifies whether the failure is system-scope or organization-scope.

Is encryption enabled by default?

MongoDB transport encryption (TLS): recommended for production and active when MONGO_TLS_ENABLED=true and certificate files are present.
Application field-level encryption: opt-in per scope through System > Encryption and Settings > Encryption; must be explicitly configured, validated, and enabled with a generated DEK.

Both are recommended for production.

Admin UI entry points: System > Encryption (system DEK and system KMS) and Settings > Encryption inside an organization (per-org DEK and KMS). A feature comparison and envelope-encryption detail are on Encryption Architecture.

[!IMPORTANT] Configure both system and organization encryption for production. Neither scope substitutes for the other.

Supported KMS providers (Admin UI)

The encryption configuration UI supports:

AWS KMS
Azure Key Vault
Google Cloud KMS
HashiCorp Vault

For each provider you configure identifiers (key ID, region, vault address, mount, etc.), validate connectivity, then generate and manage DEKs.

For how the KMS relates to field data (what the cloud sees vs what the application encrypts), see Encryption Architecture.

To align with GDPR-oriented technical controls, ensure you have:

TLS enabled for MongoDB and external endpoints.
System encryption configured, validated, and enabled.
Organization encryption configured for each active organization.
Key rotation and credential rotation procedures documented.
Backup and restore processes tested regularly.
Data retention policies defined and enforced.
Access controls and audit logging enabled for admin operations.

[!IMPORTANT] This documentation supports GDPR-oriented technical implementation but is not legal advice. Full compliance also requires legal and organizational controls in your company.

Data Processing & Encryption

On this page