> ## 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, roles, applications, providers, SSO configuration, 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 and roles people belong to, which applications can authenticate with machine-to-machine credentials, and which communication or OAuth providers are available.
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 or direct permissions;
* create, update, list, or delete groups and inspect their permissions;
* create, update, list, or delete tenant-scoped custom roles and assign their permissions, users, and groups;
* 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;
* configure the tenant's SSO policy and active OAuth 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, groups, and direct user permissions. 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. A user can also receive a direct permission without belonging to a group for that product.
Identity exposes user endpoints to list users, create users, retrieve a user, update user information, manage group assignments and direct permissions, 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.
### Roles
Access Manager uses role levels as a common convention across products. The effective actions for each role come from the product or application permission set. Identity also supports custom roles scoped to the tenant.
| Role | Typical access |
| ----------- | ------------------------------------------------------------------------------------------------------ |
| Admin | Full access, including administrative operations. |
| Editor | Can read, create, update, and delete resources. |
| Contributor | Typically can read, create, and update resources. Delete access depends on the product permission set. |
| 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.
Access Manager supplies the platform permission catalog. You can create, update, and delete tenant-scoped groups, then 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. Group assignments are one way to grant access; Identity also supports direct user-permission assignment.
You can create custom roles and assign permissions, users, and groups to them. Built-in system roles are immutable: Identity rejects attempts to create, update, or delete them. Use custom roles when the standard role levels do not express the access model you need.
A user without a group for a product can still have access through direct user permissions. Check the user's effective permissions before concluding that they cannot access a product.
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-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. |
| `flowker` | Flowker workflow 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. Identity accepts only names in this catalog when it creates or deletes applications. Some products, such as Tracer, 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.
For SSO, Identity manages one active OAuth provider per tenant. Supported provider types are Google, Microsoft, Okta, and Custom. Configuring an SSO provider disables local password login by default; configure the SSO policy explicitly if the tenant must keep local password login. The Auth SSO callback URL must be an absolute URL and appear in the application's redirect-URI allowlist, or the authorization-code relay will fail.
Before saving a candidate SSO provider, run its preflight validation. It checks the configuration, OIDC endpoint discovery, client credentials, and the callback redirect URI without creating or changing a provider, application-provider link, or application. A failed check is returned in the validation result; a malformed or unauthorized request returns an HTTP error.
For a single-tenant BYOC deployment with one fixed Casdoor organization, set `PLUGIN_AUTH_SSO_STATIC_ORGANIZATION` in Auth. Pre-login SSO then resolves every request to that organization instead of looking up an `emaildomain:` organization tag. Do not set this variable when `MULTI_TENANT_ENABLED=true`.
## 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.
The standard MFA setup and management operations are self-service: the caller's token subject must match the target user. Administrative MFA operations are separate and apply only to the methods supported by those operations.
## Architecture and identity flow
***
1. **Management request**
* An administrator or authorized client calls an Identity API.
* When Identity's Auth client is enabled and configured, the request is authenticated and checked against Access Manager permissions. Set `AUTH_REQUIRED=true` when the deployment must refuse management requests if that client is unavailable or misconfigured.
2. **Request processing**
* Identity validates the payload and applies the requested operation.
* The service updates users, groups, roles, applications, providers, provider links, SSO configuration, 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;
* custom roles and their assignments;
* applications;
* providers;
* application-provider links;
* SSO policy and OAuth-provider configuration;
* MFA setup and management;
* tenant IP allowlist configuration;
* self-service profile and phone management;
* password reset and password update flows.
When its Auth client is enabled and configured, Identity protects management access through Access Manager permissions. For technical details, check the [Identity APIs](/en/reference/access-manager/am-identity-apis) documentation.