> ## 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>
  A product with its Auth client enabled and configured rejects requests without a valid bearer token on its protected routes. This applies even if the endpoint was previously reachable without authentication.
</Warning>

On Lerian Cloud, that token also carries your tenant context, so you never pass tenant identifiers in payloads or headers yourself.

With the Identity APIs, the token is also your tenant boundary. List endpoints return only the users, groups, and applications in your tenant. 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/platform/access-manager/list-groups) to see the groups available in your environment.

    On Lerian Cloud, the list covers only your tenant. Use the returned group IDs as-is when you create or update 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/platform/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/platform/access-manager/request-access-token) with the `password` grant type.

    Use the returned access token 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/platform/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/platform/access-manager/list-users): list users.
* [Retrieve User Details](/en/reference/platform/access-manager/retrieve-user-details): inspect a user.
* [Update a User](/en/reference/platform/access-manager/update-user): update user information and group assignments.
* [Delete a User](/en/reference/platform/access-manager/delete-user): remove user access.
* [Reset a User Password](/en/reference/platform/access-manager/reset-user-password): reset a user's password through an administrative flow.
* [Update a User Password](/en/reference/platform/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/platform/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. Store the secret at once: later reads of the application do not return it.
  </Step>

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

    Identity hides internal applications from the list. On Lerian Cloud, it only returns applications of your tenant.
  </Step>

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

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

### Application catalog

Identity accepts only application names from its catalog when it creates or deletes machine-to-machine applications. [List Available Applications](/en/reference/platform/access-manager/list-available-applications) returns the catalog, with the name and display name of each application.

## Provider setup

***

Use an email provider when an application needs email delivery for MFA. 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/platform/access-manager/list-providers).
2. Link the provider to the application with [Link Provider to Application](/en/reference/platform/access-manager/link-provider-to-application).
3. If the application has multiple linked providers, use [Set Default Application Provider](/en/reference/platform/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/platform/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/platform/access-manager/verify-mfa-passcode) to confirm the method.
  </Step>

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

  <Step title="Manage MFA over time">
    Use [Get MFA Status](/en/reference/platform/access-manager/get-mfa-status), [Set Preferred MFA Method](/en/reference/platform/access-manager/set-preferred-mfa-method), or [Disable MFA](/en/reference/platform/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/platform/access-manager/initiate-mfa-challenge) with the MFA token and selected method, then [Verify MFA Login](/en/reference/platform/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/platform/access-manager/retrieve-user-information) returns their OIDC-compatible profile, and [Retrieve User Permissions](/en/reference/platform/access-manager/retrieve-user-permissions) shows the resources and actions they can reach. To end a session, call [End User Session](/en/reference/platform/access-manager/end-user-session) with the `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/platform/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.

## Tenant access rules on Lerian Cloud

***

On Lerian Cloud, Access Manager resolves your tenant from your token or application. For password grants and SSO, Auth finds the tenant from the user's email address. A person with accounts in several tenants signs in to their default tenant. If the person has no default tenant, Auth selects one. Use [List Own Tenants](/en/reference/platform/access-manager/list-own-tenants) and [Set Own Default Tenant](/en/reference/platform/access-manager/set-own-default-tenant) to see the tenants and change the default.

Identity accepts a new user, or a change to the email of a user, only when the email domain matches the `domain` field of your organization. It refuses the request with `IDE-0034` when the domain is different or when that field is empty.

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.