Skip to main content

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

Only text and json fields may set encrypted: true.

Restrictions

Encrypted fields cannot be:
  • unique
  • indexed / searchable / sortable
  • used in filters, group-by, or aggregations
Changing encryption state on an existing field requires the encryption data migration path (not a plain schema update).

API behavior

Secret reveal (scoped API key)

Requirements
  • Account-bound service API key (X-API-Key)
  • Scope: records:secrets:read
  • Collection read permission for the account
Response
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 with SNACKBASE_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

Toggling encrypted via a plain schema update is rejected. Use the dedicated encryption migration API:
Which:
  1. Converts all existing non-null values in batches (every account — partial account_id scope is refused so tenants never mix plaintext and ciphertext under one encrypted flag)
  2. Updates the field’s encrypted metadata only after every value converts
  3. On failure, rolls back data changes and leaves the schema unchanged
Verify after migration:
Webhook plaintext secrets are encrypted by Alembic revision 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
  • /health reports whether a non-default encryption key is configured (never the key itself)