> ## 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.

# Using Access Manager

> Use the Access Manager APIs to configure human access, machine-to-machine credentials, MFA challenges, and token-based authentication in your environment.

Access Manager is how you decide who reaches your Lerian products and how systems prove who they are before they call a protected API. This guide walks through that setup with the APIs.

If you'd rather work visually for the common user and application tasks, use [Access Manager via Lerian Console](/en/platform/access-manager/using-access-manager-with-midaz-console) instead.

## Before you start

***

First, make sure each product's route-level Auth client is enabled and configured with an Auth address. Protected routes then expect an `Authorization` header carrying a valid bearer token.

```text theme={null}
Authorization: Bearer <access_token>
```

<Warning>
  When a product's Auth client is enabled and configured, requests without a valid bearer token are rejected on its protected routes, even if the endpoint was previously reachable without authentication.
</Warning>

In SaaS and BYOC multi-tenant deployments, that token also carries your tenant context in trusted claims like `tenantId`, so you never pass tenant identifiers in payloads or headers yourself. Learn more about [multi-tenancy](/en/multi-tenancy).

With the Identity APIs, the token is also your tenant boundary: list endpoints return only the users, groups, and applications in your tenant, and create, update, and delete operations stay inside it.

## Human access

***

Follow this flow when a person needs to access Lerian products.

<Steps>
  <Step title="Inspect available groups">
    Use [List Groups](/en/reference/access-manager/list-groups) to see the groups available in your environment.

    Use [Retrieve Group Details](/en/reference/access-manager/retrieve-group-details) when you need to inspect a specific group's permissions before assigning it.

    In multi-tenant deployments, the list is scoped to the tenant carried by the bearer token. Use the returned group IDs as-is when creating or updating users.
  </Step>

  <Step title="Review the permission surface">
    Check each group's resources and actions before assigning it. Access Manager permissions are evaluated as exact resource-action pairs, such as `reports:get`, `users:patch`, or `transfers:read`.

    Some products use HTTP-method-style actions, while others use semantic actions such as `read`, `write`, `create`, or `process`. Use the permissions returned by the API instead of deriving permission names from endpoint paths.
  </Step>

  <Step title="Create the user">
    Use [Create a User](/en/reference/access-manager/create-user) and assign the correct groups during creation.

    Group assignment defines what the user can access. For example, assigning a read-only Midaz group lets the user inspect Midaz resources without changing them.
  </Step>

  <Step title="Request a user token">
    Use [Request an Access Token](/en/reference/access-manager/request-access-token) with the `password` grant type.

    The returned access token is used as the bearer token when the user calls protected APIs.
  </Step>

  <Step title="Refresh the token when needed">
    Use [Refresh the Access Token](/en/reference/access-manager/refresh-token) to exchange a valid refresh token for a new access token.
  </Step>
</Steps>

### User management endpoints

Use these endpoints to maintain human access over time:

* [List Users](/en/reference/access-manager/list-users) — list users.
* [Retrieve User Details](/en/reference/access-manager/retrieve-user-details) — inspect a user.
* [Update a User](/en/reference/access-manager/update-user) — update user information and group assignments.
* [Delete a User](/en/reference/access-manager/delete-user) — remove user access.
* [Reset a User Password](/en/reference/access-manager/reset-user-password) — reset a user's password through an administrative flow.
* [Update a User Password](/en/reference/access-manager/update-user-password) — update a user's password with the current password and the new one.

## Machine-to-machine access

***

When a service, job, or integration needs to call Lerian APIs without a human in the loop, give it its own application.

<Steps>
  <Step title="Create an application">
    Use [Create an Application](/en/reference/access-manager/create-an-application) to create credentials for the integration.

    Each integration should have its own application. This makes credential rotation and access review easier. The response includes the `clientId` and `clientSecret` used by Auth in the `client_credentials` flow.
  </Step>

  <Step title="Review or manage the application">
    Use [List Applications](/en/reference/access-manager/list-applications), [Retrieve Application Details](/en/reference/access-manager/retrieve-application-details), or [Delete Application](/en/reference/access-manager/delete-application) when you need to review or remove machine-to-machine access.

    Identity hides internal applications from the list. In multi-tenant deployments, it only returns applications bound to the caller's tenant organization.
  </Step>

  <Step title="Request an application token">
    Use [Request an Access Token](/en/reference/access-manager/request-access-token) with the `client_credentials` grant type.

    The returned access token is used as the bearer token for the integration's API calls.
  </Step>
</Steps>

### Current M2M application catalog

The current application catalog accepts these application names when you create machine-to-machine applications:

| Application name             | Product           |
| ---------------------------- | ----------------- |
| `midaz`                      | Midaz Ledger      |
| `plugin-fees`                | Fees Engine       |
| `plugin-crm`                 | CRM               |
| `reporter`                   | Reporter          |
| `fetcher`                    | Fetcher           |
| `plugin-br-pix-jd`           | Pix Direct JD     |
| `plugin-br-pix-indirect-btg` | Pix Indirect BTG  |
| `plugin-br-bank-transfer`    | Bank Transfer     |
| `plugin-br-pix-switch-spi`   | Pix Switch (SPI)  |
| `plugin-br-pix-switch-dict`  | Pix Switch (DICT) |
| `plugin-br-pix-switch-cob`   | Pix Switch (COB)  |
| `flowker`                    | Flowker           |
| `streaming-hub`              | Streaming Hub     |
| `br-sta`                     | STA               |
| `br-sisbajud`                | Sisbajud          |

Identity accepts only names in this catalog when it creates or deletes machine-to-machine applications.

## Provider setup

***

Use providers when an application needs a configured communication provider for MFA delivery, such as email or SMS. Browser SSO uses a separate OAuth-provider and SSO-policy configuration; see the [Identity service](/en/platform/access-manager/identity-plugin).

1. Create or review a provider with the [Providers API](/en/reference/access-manager/list-providers).
2. Link the provider to the application with [Link Provider to Application](/en/reference/access-manager/link-provider-to-application).
3. If the application has multiple linked providers, use [Set Default Application Provider](/en/reference/access-manager/set-default-application-provider) to select the default provider.

Use the application-provider endpoints when you need to list, update, unlink, or reorder provider links for an application.

## MFA setup

***

Use MFA for users who need an additional login verification step.

<Steps>
  <Step title="Start setup">
    Use [Initiate MFA Setup](/en/reference/access-manager/initiate-mfa-setup) on the signed-in user's own account and selected MFA method.
  </Step>

  <Step title="Verify setup">
    Use [Verify MFA Passcode](/en/reference/access-manager/verify-mfa-passcode) to confirm the method.
  </Step>

  <Step title="Enable MFA">
    Use [Enable MFA](/en/reference/access-manager/enable-mfa) after setup verification.
  </Step>

  <Step title="Manage MFA over time">
    Use [Get MFA Status](/en/reference/access-manager/get-mfa-status), [Set Preferred MFA Method](/en/reference/access-manager/set-preferred-mfa-method), or [Disable MFA](/en/reference/access-manager/disable-mfa) as the user's access requirements change.
  </Step>
</Steps>

During login, users with MFA enabled may need to complete [Initiate MFA Challenge](/en/reference/access-manager/initiate-mfa-challenge) with the MFA token and selected method, then [Verify MFA Login](/en/reference/access-manager/verify-mfa-login), before receiving usable access tokens. Administrative MFA changes use separate administrative operations.

## User information and session control

***

Once a user is active, a few endpoints help inspect and control that session. [Retrieve User Information](/en/reference/access-manager/retrieve-user-information) returns their OIDC-compatible profile, and [Retrieve User Permissions](/en/reference/access-manager/retrieve-user-permissions) shows the resources and actions they can reach. To end a session, call [End User Session](/en/reference/access-manager/end-user-session) with the required `id_token_hint` form field from that session; this endpoint does not select another user by ID.

## Permission checks

***

Protected products call Auth with the resource and action they need to enforce. Use [Validate User Permission](/en/reference/access-manager/validate-user-permission) when an integration needs to check an access decision explicitly.

```json theme={null}
{
  "resource": "reports",
  "action": "get"
}
```

The response tells you whether the authenticated subject is authorized for that resource-action pair.

## Multi-tenant access rules

***

The public API workflow uses the same endpoints in single-tenant and multi-tenant deployments, but multi-tenant behavior adds tenant-specific credential resolution and validation:

* In multi-tenant deployments, Auth and Identity resolve the tenant from trusted token or application context. For password grants, Auth uses tenant application credentials when available and keeps the token cache tenant-aware. Identity also permits new-user creation only when the email domain can be confirmed to match the tenant's reference administrator.
* In single-tenant deployments, Access Manager uses the configured default organization.

So don't add tenant IDs to Identity or Auth payloads unless an endpoint explicitly documents that field. After authentication, bearer-token claims scope normal Identity management and permission calls. Password and client-credentials grants resolve tenant context before a bearer token exists.