> ## 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.
# Identity service
> The Identity service manages users, groups, applications, communication providers, provider links, and MFA configuration for Access Manager deployments.
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](/en/reference/access-manager/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](/en/reference/access-manager/list-groups) and [Retrieve Group Details](/en/reference/access-manager/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](/en/reference/access-manager/create-user) or [Update a User](/en/reference/access-manager/update-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](/en/platform/access-manager/product-level-enforcement). For the API workflow that ties users, groups, and tokens together, see [Using Access Manager](/en/platform/access-manager/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. |
| `fetcher` | Fetcher ingestion 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. |
| `plugin-br-pix-switch-spi` | Pix Switch SPI automation. |
| `plugin-br-pix-switch-dict` | Pix Switch DICT automation. |
| `plugin-br-pix-switch-cob` | Pix Switch COB automation. |
| `streaming-hub` | Streaming Hub automation. |
| `br-sta` | STA file-transfer automation. |
| `br-sisbajud` | Sisbajud 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. Some products, such as Tracer and Flowker, have platform-managed M2M permission sets seeded by Access Manager but are not part of this self-service creation catalog.
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](/en/reference/access-manager/am-identity-apis) documentation.