Skip to main content
CRM manages sensitive, identity-related data. These practices help you integrate CRM correctly, protect that data, and run it safely in production. These recommendations complement the CRM data security guide, which covers encryption, hashing, and key management in detail.

​
1. Follow the correct integration flow

CRM relies on a specific order to create entities. If you skip steps or create entities out of order, you can break integrations and lose data downstream. The expected flow is:
  1. Create the holder — the individual or the organization.
  2. Link the holder to a Midaz ledger account — associate the holder with an account that already exists in the ledger.
  3. Make sure both exist — before you start any downstream flow.
Without a holder linked to a ledger account, most CRM-driven features (fees, notifications, billing, identity verification) do not work as expected.
Make sure your identifiers are correct before you create or link records. The CRM API does not validate the accuracy of the data you submit. A mismatched ledgerId or accountId can cause integration failures with the ledger or other components.

​
2. Protect your encryption keys

CRM encrypts and hashes sensitive fields before it stores them. The security of this data depends entirely on how you manage your keys.
  • Generate unique keys for LCRYPTO_HASH_SECRET_KEY and LCRYPTO_ENCRYPT_SECRET_KEY with openssl rand -hex 32.
  • Store keys in a secret manager (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault, or equivalent). Never hardcode them in configuration files, source code, or version control.
  • Plan for key rotation. If a key is compromised, generate a new one and re-encrypt all affected data. This is a manual process, so design your operational runbooks for it.
  • Use Kubernetes Secrets in production. Reference existing secrets via useExistingSecret and existingSecretName in your Helm values instead of storing keys inline.
For the full list of protected fields and encryption strategies, see CRM data security.

​
3. Never store sensitive data in metadata

The metadata object in CRM entities is not encrypted. CRM stores it in plain text for non-sensitive, auxiliary information only. Do not use metadata for:
  • Personal identification numbers (CPF, SSN, passport)
  • Financial account details
  • Contact information (email, phone)
  • Any data subject to LGPD, GDPR, or similar regulations
If you need to store a sensitive attribute that is not in the protected fields list, contact your Lerian representative to discuss options.

​
4. Do not expose CRM directly on edge layers

CRM runs inside the Midaz ledger and exposes an internal API. If you expose it directly through API gateways, load balancers, or frontend applications, you increase your attack surface. You also bypass application-level access controls. Instead:
  • Route CRM traffic through your backend services or an internal API layer.
  • Use Access Manager to enforce authentication and authorization if you need fine-grained control.
  • Restrict network access to the ledger pods with Kubernetes NetworkPolicies or your cloud provider’s security groups.

​
5. Use soft delete as the default

CRM supports both soft delete and hard delete:
  • Soft delete (default): CRM marks the record with a deletedAt timestamp. The record drops out of standard queries but stays in the database for audit and recovery.
  • Hard delete: CRM requests removal of the record, subject to your deployment’s retention and compliance rules. Where legal, regulatory, audit, or record-keeping obligations require retention, CRM does not guarantee physical removal.
For most cases, soft delete is the safer choice. It preserves audit trails and lets you recover data you delete by mistake. Reserve hard delete for cases where regulations demand complete removal (for example, GDPR right-to-erasure requests).
Confirm your retention and legal-hold policy before you run a hard delete. The GDPR right to erasure (Article 17) is not absolute. Where legal, regulatory, audit, or record-keeping obligations require data retention, they can take precedence and restrict erasure.

​
6. Validate data before sending it to CRM

CRM acts as a neutral, persistent data layer. It does not enforce business rules, validate document formats, or check KYC compliance. Data integrity is your responsibility. Before you create or update a record:
  • Validate document formats (CPF, CNPJ, passport numbers) on your application layer.
  • Make sure the ledgerId and accountId values point to real entities in Midaz.
  • Sanitize inputs so you do not store malformed or inconsistent data.

​
7. Keep CRM and Midaz versions aligned

CRM ships inside the Midaz ledger binary, so it shares the Midaz version. Before you upgrade:
  • Check the version compatibility table to confirm your target version.
  • Test the upgrade in a staging environment before you apply it to production.
  • Back up your MongoDB data and Helm values before any major upgrade.
For upgrade procedures, see the Helm upgrade guide.

​
8. Monitor database health and performance

CRM uses MongoDB for data storage. In production:
  • Monitor connection pool usage. The default MONGO_CRM_MAX_POOL_SIZE is 1000. Adjust it for your traffic patterns and replica count.
  • Set up alerts for MongoDB disk usage, replication lag, and connection saturation.
  • Enable backups. Whether you use the bundled Bitnami MongoDB or an external instance, run automated backups and test them regularly.
  • Enable OpenTelemetry (ENABLE_TELEMETRY: true) to collect traces and metrics from CRM. Integrate with your observability stack for end-to-end visibility.

​
9. Review the security recommendations

CRM handles personal and sensitive data. Beyond CRM-specific practices, make sure your deployment follows the platform-wide Security recommendations, which cover:
  • Network segmentation and Zero Trust Architecture
  • TLS 1.2+ enforcement for all communications
  • IAM and RBAC configuration
  • Incident response planning
  • Patch management and vulnerability scanning