Encrypted collection fields
SnackBase can encrypt selected collection fields so credential plaintext is never stored in the database or returned by normal record APIs.Marking a field as encrypted
Onlytext and json fields may set encrypted: true.
Restrictions
Encrypted fields cannot be:- unique
- indexed / searchable / sortable
- used in filters, group-by, or aggregations
API behavior
Secret reveal (scoped API key)
- Account-bound service API key (
X-API-Key) - Scope:
records:secrets:read - Collection read permission for the account
When
fields is omitted, all encrypted fields are returned only if the record
has 20 or fewer encrypted fields; otherwise you must select fields explicitly.
SDK
Deployment key
Encrypted values use Fernet withSNACKBASE_ENCRYPTION_KEY.
- Production rejects the default key — set a strong value before deploy:
openssl rand -hex 32 - Keep the key outside the database and application artifact
- Backups of encrypted data are useless without the same key
- Key rotation is not supported in this release; changing the key makes existing ciphertext unreadable
Migrating existing fields
Togglingencrypted via a plain schema update is rejected. Use the dedicated
encryption migration API:
- Converts all existing non-null values in batches (every account — partial
account_idscope is refused so tenants never mix plaintext and ciphertext under oneencryptedflag) - Updates the field’s
encryptedmetadata only after every value converts - On failure, rolls back data changes and leaves the schema unchanged
20260803_wh_secrets.
Apply migrations before deploying code that expects ciphertext at rest.
Security notes
- PII masking is not a substitute for encryption
- Audit logs and events record field names and operation metadata only, never secret values
- Superadmin JWT sessions do not bypass secret reveal authorization
/healthreports whether a non-default encryption key is configured (never the key itself)