> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Best practices

> Follow CRM production best practices covering integration flow, encryption key management, metadata safeguards, and safe operational workflows.

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](/en/midaz/crm/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.

<Warning>
  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.
</Warning>

## 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](/en/midaz/crm/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](/en/midaz/crm/crm-data-security#protected-fields), 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](/en/platform/access-manager/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).

<Note>
  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.
</Note>

## 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](/en/platform/plugins/midaz-version-compatibility) 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](/en/platform/helm/midaz/midaz-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](/en/midaz/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