Skip to main content
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 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.
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.
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:

​
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 application catalog accepts these application names when you create machine-to-machine applications: 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.
  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 on the signed-in user’s own account and selected 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 with the MFA token and selected method, then 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 returns their OIDC-compatible profile, and Retrieve User Permissions shows the resources and actions they can reach. To end a session, call 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 when an integration needs to check an access decision explicitly.
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.