Guides template
This template provides a standard structure for writing product or plugin guides in the Lerian documentation. All guides should be:
- Task-oriented
- Contextual and didactic
- Consistent in structure and voice
- Easy to follow with real examples and cross-links
Use this as your starting point for writing a new guide.
Main page
The main page must have the following structure:
Intro
Start the page with a short introduction (2–3 paragraphs max), explaining what it is, why it exists, and what problem it solves.
TipUse real context to show relevance.
Why use it?
Highlight the benefits, differentials, and ideal use cases. Feel free to include:
- Performance gains
- Security improvements
- Compliance value
- Real-world scenarios
Key concepts
Define the most important terms, roles, or components. This section builds shared understanding and avoids ambiguity.
Technical Specs
Document the implementation details developers need to know. Include:
- Required environment or dependencies
- Data models or schemas
- Internal validation rules
- Configuration variables
5. Best Practices
Offer practical advice to help users use the product safely and efficiently. Include tips on security, performance, and common pitfalls.
Using the plugin page
Create a page that is a step-by-step tutorial for using the product.
TipLink to specific API references, UI screens, and include real payload examples when possible.
(Optional) Child Pages
Use separate pages when you need to explain:
- System architecture, or how components interact
- Business logic, formulas, or algorithms
- Performance considerations or known limitations
- Security design (e.g., encryption, RBAC model)
ImportantKeep the main guide focused. Move complex deep dives to child pages.
Examples
Main page
# CRM
The **CRM (Customer Relationship Manager)** plugin is a data integration layer that manages essential registration data tied to a Midaz account user—also referred to as the **Holder**, **Owner**, or **Customer**. In Midaz, this user is represented by the `Entity`.
This plugin **does not belong to the ledger’s transactional domain**. Instead, it enriches ledger accounts with business-relevant attributes without interfering with the ledger's logic or performance.
CRM is where user metadata lives. It's not about balances, transfers, or fees—it's about who's behind the account and what you need to know to operate your business.
# Why use the CRM?
***
Midaz ledger accounts are generic by design, built to be transaction-first and domain-agnostic. The CRM plugin steps in to add meaning to those accounts, linking each one to detailed user profiles and business contexts.
### Example use cases
* **Banking (individuals and businesses)**\
CRM stores identifiers like CPF or CNPJ, address, contact details, or account numbers, while Midaz handles the exact same transaction logic for either customer type.
* **Supply chains (supplier, factory, retailer)**\
CRM tracks metadata like supplier ID, warehouse location, or contractual info. This data doesn’t belong in the transaction, but it’s essential when deciding whether a transaction should be allowed.
> 👍 Tip
>
> CRM is a separate plugin. If you'd like to learn more or evaluate it for your use case, [get in touch with our team](https://lerian.studio/contact).
# Entities
***
CRM revolves around two core entities:
* **Holder** – The core entity in CRM, representing the persona associated with a ledger account on Midaz. It stores identity-related attributes and individual characteristics.
* **Alias Account** – Defines the business context associated with a [Ledger Account](doc:accounts) in **Midaz Ledger**, including financial details such as bank account information.
In *Figure 1*, you can find an illustration of how the CRM entities are connected to Midaz.
<Image align="center" alt="Figure 1. An illustration of how CRM entities connect to Midaz" border={true} caption="Figure 1. An illustration of how CRM entities connect to Midaz" src="https://files.readme.io/4980de15af2d1c64253d76038e57da9ba968a03eb62894dce8837ed635e92dd6-entities_new.jpg" />
# Design principles
***
The CRM plugin is built for:
* **Separation of concerns**: Keeps user profile data out of transactional logic.
* **System performance**: No user-level orchestration inside Midaz core services.
* **Integration flexibility**: Each client can use CRM data to drive custom rules, without altering the ledger.
> ❗️ Important
>
> CRM doesn’t validate ledger-level rules or compliance processes like KYC. It’s a neutral, persistent data layer designed for maximum interoperability.
# API behavior
***
CRM is implemented as a standalone registry API. It provides persistence and structured access to non-transactional data linked to accounts on Midaz.
* It does **not** enforce validations such as user status, risk profile, or document verification.
* It is **agnostic to the asset, ledger, or grouping logic** used in Midaz accounts.
* It ensures consistent access to holder metadata without polluting the transactional layer.
# Security & compliance
***
Lerian provides Midaz and its plugins as on-premise components—meaning **you stay in control** of your infrastructure, compliance policies, and user data lifecycle.
That said, we ensure security best practices by default:
* **Data in transit** is encrypted with industry-standard protocols.
* **Data at rest** is protected by encryption and fine-grained access controls.
We trust our clients to define and enforce their own policies around LGPD and other regional data protection regulations. CRM simply provides the structure.
# Data deletion strategies
***
At Lerian, we treat data ownership seriously. That’s why the CRM plugin gives you full control over how information is removed, with two built-in options:
* **Soft delete** (default): The record stays in the database but is flagged as deleted. This is useful if you need to keep an audit trail or recover information later.
* **Hard delete**: If your internal policy requires complete removal, you can use a specific command to delete the data permanently—no recovery.
You're in charge. We don’t impose limits or assumptions on your data strategy. Each institution defines its own rules, and the plugin adapts securely and reliably.
# Access control
***
Need to restrict who can access your CRM data? You can enable our [Access Manager](doc:auth-identity) plugin to help you restrict who has access to the data.
### Enabling Access Manager
To enable access control, first make sure **Access Manager** is installed. Then, open the `.env` file located in the root of the CRM folder using any text editor, and set the following environment variables:
```text
# AUTH
PLUGIN_AUTH_ADDRESS=http://plugin-auth:4000
PLUGIN_AUTH_ENABLED=true
```
The **CRM plugin** will start enforcing access permissions based on your Auth setup.
> 👍 Tip
>
> Access Manager is available as a part of the Enterprise model. If you'd like to learn more or evaluate it for your use case, [get in touch with our team](https://lerian.studio/contact).
Child page
# CRM data security
Handling personal and sensitive data is a serious responsibility. As a centralized hub for individual-related records, the CRM plugin is designed with security at its core, ensuring user privacy, reducing the risk of misuse, and aligning with global data protection standards.
## Why does this matter?
Every regulation (from GDPR to LGPD) shares the same principle: personal data should only be used for the purpose the user consented. The **CRM plugin** integrates with Midaz to support both transactional and non-transactional flows, and must ensure that sensitive data used in these processes is properly safeguarded.
Although Lerian doesn't offer cybersecurity services, we follow strict information security practices in all software we ship.
# Security responsibilities
***
As an on-premise technology provider, Lerian does not oversee or enforce the cybersecurity policies of our clients. We respect the trust-based relationship each institution has with its end users and operate under the assumption that they follow the LGPD and any other relevant regional or industry-specific data protection regulations.
That said, Lerian is committed to delivering technology that adheres to strong, market-aligned security practices. This ensures that sensitive CRM data is protected as follows:
## In transit
All data exchanged with the CRM is secured with **TLS encryption over HTTPS**. From the moment a request hits the system, whether it’s creating or updating a holder or account, sensitive fields are encrypted *before* being written to the database.
## At rest
Because the CRM runs on-premise, **encrypting disks or volumes is the client’s responsibility**. Still, we strongly recommend implementing this measure to add a robust layer of protection.
# How we protect data
***
The CRM plugin employs various protection methods based on the nature of the data and its intended use.
* **Encryption** is used when the system might need to access the original value, such as names or contact information.
* **Hashing** is used when values don’t need to be shown again but must remain verifiable, like identifiers used for filtering or lookup.
> 🚧 Attention
>
> Sensitive data is protected as soon as it reaches the CRM. It’s never stored or processed in raw form.
## Encryption and hashing strategies
To safeguard sensitive information while supporting application functionality, the CRM uses a combination of cryptographic techniques aligned with industry best practices.
### Encryption
For fields that need to be retrieved or shown, such as personal names or emails, the CRM encrypts each value using strong, symmetric encryption. This ensures that even if database contents are accessed directly, original values remain unreadable without proper authorization.
The encryption process also includes a random component to guarantee that identical values never produce the same encrypted output.
### Hashing
Certain fields are hashed to allow secure filtering without exposing the original value. These hashed values are stored in a separate internal structure that supports fast, secure lookups.
> 📘 Note
>
> In some cases, fields may be hashed solely to meet internal database constraints, even if they aren’t searchable.
## Key management
The CRM uses encryption and hashing keys that must be securely generated, stored, and managed by the deployment team. Keys should follow strong cryptographic standards and never be hardcoded or exposed in source code or version control.
> ❗️ Important
>
> Protect your keys using a dedicated secret manager or secure storage solution. If a key is compromised, you must rotate it and re-encrypt or re-hash affected data.
## Protected fields
Below is a list of fields that undergo protection processes within the CRM. You don’t need to concern yourself with the specifics of how this works; just ensure that you avoid entering sensitive data in areas not included here.
> ❗️ Important
>
> Never store sensitive information in the `metadata` object.
### Holder
* `name`
* `document`
* `contact.primaryEmail`
* `contact.secondaryEmail`
* `contact.mobilePhone`
* `contact.otherPhone`
* `naturalPerson.motherName`
* `naturalPerson.fatherName`
* `legalPerson.representative.name`
* `legalPerson.representative.document`
* `legalPerson.representative.email`
### Account
* `document`
* `bankingDetails.account`
* `bankingDetails.iban`
# Best practices & recommendations
***
Data encryption in the **CRM plugin** is designed to add a strong security layer, ensuring that even if the database is compromised, sensitive data remains inaccessible in its original form.
Decryption is only possible via a valid key or through authenticated and authorized service calls. That’s why key security is critical: if a key is leaked, the application cannot protect your data on its own.
To keep your environment safe, we strongly recommend:
* **Avoid exposing CRM services** directly on edge layers like gateways or frontend apps.
* **Never store sensitive data in metadata fields**, they are not encrypted.
* **Enforce governance** for managing access to the production environment and related tooling.
* **Use secure key managers** with strict access controls to safeguard your secrets.
* **Encrypt disks or volumes** to protect data at rest.
If a key is compromised or needs to be rotated, it's **your responsibility to generate a new one and re-encrypt affected data** using the CRM’s available services.
> 🚧 Attention
>
> Data security is a shared responsibility. The **CRM plugin** gives you the building blocks—make sure your deployment uses them wisely.
Using the plugin
# Using CRM
The **CRM plugin** helps you manage real-world person data across your platform, enabling better segmentation, validation, and personalization across your ecosystem.
# Enabling CRM
***
After installing CRM, open the `.env` file with any text editor and update the following variables before getting started:
```env
# DATA SECURITY
LCRYPTO_HASH_SECRET_KEY=my-hash-secret-key
LCRYPTO_ENCRYPT_SECRET_KEY=my-encrypt-secret-key
```
* `LCRYPTO_HASH_SECRET_KEY`: This is your hashing key. It checks data integrity and confirms that requests come from a trusted source.
* `LCRYPTO_ENCRYPT_SECRET_KEY`: This is your encryption key. It protects sensitive data by encrypting it and decrypts it when needed.
You’ll need to generate these keys yourself and paste them into the `.env` file. You can use the following command to generate the keys:
* Each key must be unique, so you will have to run the command **twice**, once for each key, to generate separate, secure values.
### Generate a hashing key
```bash
openssl rand -hex 32
```
### Generate an encryption key
```bash
openssl rand -hex 32
```
> ❗️ Important
>
> **Keep your keys safe**.
>
> Once generated, store your keys securely. We recommend using a Secret Manager to protect them from exposure.
# Typical usage
***
Here’s how you can get started:
### Step 1 – Create the Holder
Start by creating a **holder**, which represents an individual or organization in the system.
* To do so, use the [Create a Holder](ref:create-holder) endpoint.
> ⚠️ Attention
>
> While many fields are marked as optional at the API contract level, some plugins (like CRM or KYC integrations) may require them.
>
> If you're unsure, check the plugin's specific requirements before proceeding.
Also note:
* The API doesn’t validate the **accuracy** of the data.
* Supplying incorrect values (like mismatched `ledgerId` or `accountId`) may result in integration failures, especially with external providers or the Ledger component.
**Take extra care to provide valid identifiers and real data when needed.**
<details>
<summary><b>Managing Holders</b></summary>
You can also perform actions such as:
* [List Holders](ref:list-holders) – View all holders in your system.
* [Retrieve a Holder](ref:retrieve-holder) – Get details of a specific holder.
* [Update a Holder](ref:update-holder) – Make changes to a holder's data.
* [Delete a Holder](ref:delete-holder) – Soft-delete or remove the user information permanently.
</details>
### Step 2 – Connect the holder to Midaz using an Alias Account
Once the holder is created, use the [Create an Alias Account](ref:create-alias-account) endpoint to set up an Alias Account (a **CRM-level** account that represents the Midaz Account) and link the Holder to it in a single step. This link is key to:
* Tracking transactions tied to the holder.
* Enabling fees, notifications, and other account-level features.
* Powering downstream flows like billing and identity verification.
**Without this connection, most CRM-driven features won’t work as expected.**
<details>
<summary><b>Managing Alias Accounts</b></summary>
You can also perform actions such as:
* [List Alias Accounts for a Holder](ref:list-alias-accounts-holders) – View all Alias Accounts linked to a specific Holder.
* [Retrieve Alias Account details](ref:retrieve-alias-account) – Get details of a specific Alias Account.
* [Update an Alias Account](ref:update-alias-account) – Make changes to the details of an Alias Account.
* [Delete an Alias Account](ref:delete-alias-account) – Soft delete or remove the Alias Account permanently.
</details>
# What happens next?
***
With holders properly created and linked, you can now:
* Enrich CRM data with additional plugins (e.g., KYC, scoring, segmentation).
* Trigger workflows that depend on identity or organizational attributes.
* Validate or filter transactions based on person-level data.
The CRM plugin lays the foundation; what you build on top is up to you.
Updated 9 days ago