Using Access Manager

Use Access Manager APIs to configure human access, machine-to-machine access, MFA, and token-based authentication.

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

Authorization: Bearer <access_token>

Requests without a valid bearer token are rejected after Access Manager is enabled, even if the endpoint was previously reachable without authentication.

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.

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.

1. Inspect available groups

   Use List Groups to see the groups available in your environment.

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

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

3. Create the user

   Use Create a 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.

4. Request a user token

   Use Request an Access Token with the password grant type.

   The returned access token is used as the bearer token when the user calls protected APIs.

5. Refresh the token when needed

   Use Refresh the Access Token to exchange a valid refresh token for a new access token.

User management endpoints

Use these endpoints to maintain human access over time:

• List Users — list users.
• Retrieve User Details — inspect a user.
• Update a User — update user information and group assignments.
• Delete a User — remove user access.
• Reset a User Password — reset a user’s password through an administrative flow.
• Update a 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.

1. Create an application

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

2. Review or manage the application

   Use List Applications, Retrieve Application Details, or 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.

3. Request an application token

   Use Request an Access Token with the client_credentials grant type.

   The returned access token is used as the bearer token for the integration’s API calls.

Current M2M application catalog

The current Access Manager seed and migrations define M2M permissions for these application names:

Application name	Product
midaz	Midaz Ledger
plugin-fees	Fees Engine
plugin-crm	CRM
reporter	Reporter
plugin-br-pix-direct-jd	Pix Direct JD
plugin-br-pix-indirect-btg	Pix Indirect BTG
plugin-br-bank-transfer	Bank Transfer

Other products listed in the enablement matrix, such as Tracer, Flowker, and Fetcher, do not currently define standard M2M application names in the Access Manager seed.

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.
2. Link the provider to the application with Link Provider to Application.
3. If the application has multiple linked providers, use 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.

1. Start setup

   Use Initiate MFA Setup for the user and MFA method.

2. Verify setup

   Use Verify MFA Passcode to confirm the method.

3. Enable MFA

   Use Enable MFA after setup verification.

4. Manage MFA over time

   Use Get MFA Status, Set Preferred MFA Method, or Disable MFA as the user’s access requirements change.

During login, users with MFA enabled may need to complete Initiate MFA Challenge and 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 returns their OIDC-compatible profile, and 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.

Permission checks

---

Protected products call Auth with the resource and action they need to enforce. Use Validate User Permission when an integration needs to check an access decision explicitly.

{
  "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.