> ## 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 Access Manager is enabled for the products you want to protect. From that point on, every protected API expects an `Authorization` header carrying a valid bearer token.

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

<Warning>
  Requests without a valid bearer token are rejected after Access Manager is enabled, 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-direct-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)  |
| `streaming-hub`              | Streaming Hub     |
| `br-sta`                     | STA               |
| `br-sisbajud`                | Sisbajud          |

Do not create applications with names outside this catalog unless your environment has a custom permission set for that application.

## Provider setup

***

Use providers when an application needs a configured communication provider for MFA delivery, such as email or SMS.

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) for the user and 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) and [Verify MFA Login](/en/reference/access-manager/verify-mfa-login) before receiving usable access tokens.

## User information and session control

***

Once a user is active, a few endpoints help you inspect and control the 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. When you need to cut a session short and revoke its active tokens, call [End User Session](/en/reference/access-manager/end-user-session).

## 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 API workflow is identical in single-tenant and multi-tenant deployments. The only thing that changes is where Access Manager gets the tenant scope from:

* In multi-tenant deployments, Auth and Identity resolve the tenant from trusted token or application context.
* 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. For the normal user, group, application, token, and permission flows, the bearer token is your single source of tenant scope.