Identity service

Manage users, groups, applications, communication providers, provider links, and MFA configuration with the Identity service.

Identity is the management service for Access Manager. It’s where administrators define who can access Lerian products: which groups people belong to, which applications can authenticate with machine-to-machine credentials, and which communication providers are available for MFA delivery.

Identity does not issue access tokens or make runtime authorization decisions. Auth uses the identity data managed here to authenticate subjects and evaluate permissions.

Use Identity when you need to:

• create, update, list, or delete users;
• assign users to product groups;
• list predefined groups and inspect their permissions;
• create, list, retrieve, or delete machine-to-machine applications;
• create, update, list, retrieve, or delete communication providers;
• link providers to applications and select the default provider;
• initiate, verify, enable, disable, review, or change MFA settings for users;
• reset or update user passwords.

Users and groups

---

Human access is managed through users and predefined groups. A group represents a permission set for a product or Access Manager area.

For example, a user can be assigned to a Midaz viewer group to inspect ledger data without changing it, and to a Reporter contributor group to create report templates. If the same user has no group for Fees, they do not receive Fees access.

Identity exposes user endpoints to list users, create users, retrieve a user, update user information and group assignments, delete users, update passwords, and reset passwords. User and group list endpoints are paginated with page and limit.

In multi-tenant deployments, users and groups are scoped from the bearer token. The service reads the tenant organization from the authenticated context and returns only the users and groups that belong to that tenant. In single-tenant deployments, the same endpoints return the environment-wide set.

When you create or update a user, send the group IDs returned by List Groups. The API handles the internal organization prefixing; clients should not build Casdoor-style organization/group values manually.

Do not send tenant ownership in user payloads. Identity derives the tenant scope from the bearer token, then applies the requested user and group changes inside that tenant.

Role levels

Access Manager uses consistent role levels across products:

Role	Typical access
Admin	Full access, including administrative operations.
Editor	Can read, create, update, and delete resources.
Contributor	Can read, create, and update resources, but cannot delete.
Viewer	Read-only access.

Roles are scoped per product or application. A user can be an Editor in Midaz, a Viewer in Reporter, and have no access to Fees.

Permission sets are predefined by Lerian. Use List Groups and Retrieve Group Details to inspect the groups available in your environment, and assign users by sending the returned group IDs back through Create a User or Update a User.

If a user has no assigned group for a product, the user has no access to that product, not even read-only access.

For the resource-action model, the action vocabularies used by each product, and how routes are protected at runtime, see Product-level enforcement. For the API workflow that ties users, groups, and tokens together, see Using Access Manager.

Applications

---

Applications represent machine-to-machine clients for the client_credentials grant. Use them when a service, job, or integration needs to authenticate without a human user.

An application stores the clientId and clientSecret used by Auth during the client_credentials flow. After creating an application, the integration can request an access token from Auth and call protected Lerian APIs according to its configured permissions.

Identity supports:

• listing applications;
• creating applications;
• retrieving application details;
• deleting applications.

For example, a reconciliation job can use a Bank Transfer application to request a token and call only the endpoints needed for its workflow.

The current M2M permission catalog includes these application names:

Application name	Typical use
midaz	Core ledger automation.
plugin-fees	Fee package, fee, and estimate automation.
plugin-crm	CRM holder and alias automation.
reporter	Report and template automation.
plugin-br-pix-direct-jd	Pix Direct JD automation.
plugin-br-pix-indirect-btg	Pix Indirect BTG automation.
plugin-br-bank-transfer	Bank Transfer automation.

Application names are product identifiers, not UI display labels. Do not use names outside this catalog unless your environment has explicitly added that application and its permission set.

Identity filters internal applications from the public application list. In multi-tenant mode, it also returns only applications bound to the caller’s tenant organization.

Tenant scoping

In multi-tenant deployments, Identity uses the authenticated context as the tenant boundary for management operations:

• user operations apply to the caller’s tenant organization;
• group lists include only permission groups available in that tenant;
• application lists include only machine-to-machine applications bound to that tenant;
• application credentials created for an integration belong to the tenant that created them.

This keeps operational access local to the tenant. An administrator token from one tenant cannot list or mutate another tenant’s users, groups, or applications through the public Identity APIs.

Communication providers

---

Communication providers define the email or SMS delivery services available to applications, including MFA flows. They are managed separately from applications so the same provider can be reused and controlled consistently.

Identity supports:

• listing providers;
• creating providers;
• retrieving provider details;
• updating providers;
• deleting providers.

Identity also supports application-provider links:

• list providers linked to an application;
• link a provider to an application;
• update a provider link;
• unlink a provider from an application;
• set the default provider for an application.

Use a default provider when an application has more than one linked provider and needs a preferred authentication route.

MFA management

---

Identity manages MFA configuration for users. Auth uses that configuration during login when MFA is required.

Identity supports:

• initiating MFA setup;
• verifying an MFA passcode during setup;
• enabling MFA after verification;
• disabling MFA;
• retrieving the current MFA status;
• setting the preferred MFA method.

MFA can use supported methods such as authenticator app, email, or SMS, depending on the environment configuration and the user profile data available.

Architecture and identity flow

---

1. Management request
   • An administrator or authorized client calls an Identity API.
   • The request is authenticated and checked against Access Manager permissions.
2. Request processing
   • Identity validates the payload and applies the requested operation.
   • The service updates users, groups, applications, providers, provider links, or MFA configuration in the configured identity system.
3. Runtime use
   • Auth reads the resulting identity data during token, permission, and MFA flows.
   • Protected Lerian products rely on Auth decisions before processing product operations.

API overview

---

Identity exposes APIs for:

• users;
• groups;
• applications;
• providers;
• application-provider links;
• MFA setup and management;
• password reset and password update flows.

Access is secured by strict permission controls. For technical details, check the Identity APIs documentation.