> ## 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.
# Partners
> Give each of your own customers its own credentials, and limit what it can do, where, from which addresses, and for how long.
This feature is available only in Staging for testing and is not yet available in Production.
A partner is one of your own customers that calls your Lerian platform from its own systems. Access Manager lets you give each partner its own credentials. You decide what the partner can do, in which part of your data, from which network addresses, and for how long.
Think of a building with many offices. You are the owner and hold every key. A partner gets a badge that opens only the doors you choose, works only during the hours you set, and stops working the moment you cancel it.
## Why segregate access
***
When several customers call your platform, one shared credential gives each of them the access of all of them. Partners replace that with one set of limits per customer:
* **Least privilege.** Each partner gets only the actions and the data it needs, and nothing above what your own team can do.
* **Credentials per partner.** Each partner holds its own credentials. You can revoke one partner without touching the others.
* **Immediate revocation.** Suspending a partner, or reaching the end of its validity window, refuses its next request, even with a token it already holds.
* **Network restriction.** A partner can call only from the addresses you list for it.
* **Validity windows.** Access can start and end on dates you choose. A pilot that ends on a date needs no reminder to switch off.
* **Clear accountability.** Each request carries the partner's own credential, so every action traces back to one partner.
## The building blocks
***
A tenant holds organizations, and an organization holds ledgers. A partner is a record of the tenant, and the rows after it describe what a partner gets.
| Concept | What it is | Example |
| - | - | - |
| **Tenant** | Your environment on the Lerian platform. Your users, applications, and partners live inside it. | One tenant for staging and another one for production. |
| **Midaz organization** | A company or business unit inside your tenant. A tenant can hold several organizations. | "Organization North" and "Organization South". |
| **Ledger** | A set of books inside one Midaz organization. An organization can hold several ledgers. | "Ledger N1" and "Ledger N2" inside Organization North. |
| **Partner** | A record inside your tenant that represents one of your own customers. A partner is not a tenant. | "Partner A". |
| **Partner application** | A machine-to-machine credential (a client ID and a client secret) that belongs to one partner. A partner can have several. | One application for Midaz and another one for Tracer. |
| **Permissions** | **What** the partner can do: a product, its resources, and the actions on them. | Midaz: `accounts` and `transactions`, with `get` and `post`. |
| **Scope** | **Where** the partner can do it: which organization, which ledgers, which accounts. Each product publishes the restrictions it accepts. | Only Organization North, only Ledger N1. |
| **Ceiling** | The most you can give a partner in a product: what the product's editor role holds in your tenant. | If your tenant cannot delete accounts, no partner can. |
| **Partner IP allowlist** | The network addresses the partner's credentials can call from. | Only `203.0.113.10`. |
| **Validity window and state** | When the partner's credentials work (`validFrom` and `validUntil`), and whether the partner is `active` or `suspended`. | Valid for 90 days, then refused. |
## How the pieces fit together
***
The tenant is a hard boundary. Data in your staging tenant never mixes with data in your production tenant. Inside a tenant, organizations and ledgers separate your data **logically**: Access Manager uses the scope of each partner to keep each partner inside its own part.
* **Tenant: Production.** Your staging tenant is a separate one.
* **Organization North**
* **Ledger N1.** Partner A writes accounts and transactions here.
* **Ledger N2**
* **Accounts 1 and 2.** Partner C reads only these two accounts.
* **Organization South.** Partner B reads the whole organization, for 90 days.
* **Ledger S1**
* **Ledger S2**
All three partners live in the same tenant. None of them can see the part of another one.
## Example: three partners in one tenant
***
Your company runs one tenant per environment. The production tenant holds two Midaz organizations, North and South. Three of your customers need API access.
### Partner A: writes in one ledger, from one address
| Setting | Value |
| - | - |
| Permissions | Midaz: `accounts` with `get`, `post`, `patch`; `transactions` with `get`, `post` |
| Scope | Organization North, Ledger N1 |
| IP allowlist | Its own list: `203.0.113.10/32` |
| Validity | No time limit |
| Request | Result |
| - | - |
| Create a transaction in Ledger N1, from `203.0.113.10` | Allowed. |
| List the accounts of Ledger N1 | Allowed. |
| List the accounts of Ledger N2 | Refused with `403`. Ledger N2 is outside its scope. |
| Delete an account in Ledger N1 | Refused with `403`. `delete` is not in its permissions. |
| Any request from another address | Refused with `403` and code `AUT-0021`. |
You also cannot give Partner A the right to create ledgers. Creating a ledger acts on the whole organization, which is wider than one ledger. Access Manager refuses that change with `IDE-1056`, and the Console shows the line as "Outside the scope".
### Partner B: reads a whole organization for 90 days
| Setting | Value |
| - | - |
| Permissions | Midaz: `ledgers`, `accounts`, `balances`, `transactions`, all with `get` |
| Scope | Organization South |
| IP allowlist | Uses your tenant's list |
| Validity | `validFrom` `2026-11-01T00:00:00Z`, `validUntil` `2027-01-30T23:59:59Z` |
| Request | Result |
| - | - |
| Read the balances of any ledger in Organization South, inside the window | Allowed. |
| Create a transaction in Organization South | Refused with `403`. It can only read. |
| Read anything in Organization North | Refused with `403`. Organization North is outside its scope. |
| Any request before `2026-11-01T00:00:00Z` or after `2027-01-30T23:59:59Z` | Refused with `401` and code `AUT-1010`. A new token is refused with the same code. |
### Partner C: reads two accounts, then gets suspended
| Setting | Value |
| - | - |
| Permissions | Midaz: `accounts`, `balances`, `transactions`, all with `get` |
| Scope | Organization North, Ledger N2, two account IDs |
| IP allowlist | Its own list: `198.51.100.0/24` |
| Validity | No time limit |
| Request | Result |
| - | - |
| Read the balances and transactions of its two accounts | Allowed. A restriction on an account also covers the balances, transactions, and operations of that account. |
| Read a third account in Ledger N2 | Refused with `403`. |
| List all the accounts of Ledger N2 | Refused with `403`. Once you restrict a type by ID, the partner cannot list or create items of that type. |
| Any request after you suspend Partner C | Refused with `401` and code `AUT-1009`, also with a token issued before the suspension. When you reactivate it, the same credentials work again. |
## How a request is decided
***
The checks below run on every request that a partner's credential sends to a product. They run in this order, and the first one that fails stops the request.
1. **Token.** The partner's system exchanges its client ID and client secret for an access token, and sends the token with the request.
2. **Partner.** Access Manager finds the partner that the credential belongs to.
3. **Network address.** Access Manager compares the caller's address with the partner's own list. A partner without a list of its own uses your tenant's list. A refusal returns `403` with `AUT-0021`.
4. **State and validity.** A suspended partner, or one outside its validity window, is refused with `401`: `AUT-1009` for suspended, `AUT-1010` for outside the window.
5. **Permissions.** The product, the resource, and the action must be in the partner's permissions. A refusal returns `403`.
6. **Scope.** The organization, ledger, account, or other item that the request names must be inside the partner's scope. A refusal returns `403`.
7. If every check passes, the product runs the request.
The product does not tell the caller whether the permissions or the scope refused the request. Both return the same `403`, so a partner cannot use refusals to find out which items exist outside its scope.
## What you need to know
***
* **Permissions and scope must both match.** A partner reaches only what both allow. Permissions without scope on a product with a required restriction cannot be saved.
* **Suspension and the end of the validity window apply at once.** The partner's next request is refused, even with a token it already holds. A suspended partner also cannot get new tokens.
* **Every other change applies from the next request.** That includes new permissions, a narrower scope, and a new IP allowlist.
* **A partner never gets more than your tenant has.** The ceiling is what the product's editor role holds in your tenant. If that role later loses a permission, the partner loses it too.
* **Access Manager does not check that scope IDs exist in the product.** It stores the IDs you enter. Copy them from the product's own API or Console.
* **A product shown as "not ready for partners" has not published its list of restrictions yet.** You cannot give a partner access to that product until it does.
* **A request that leaves out an item the scope restricts is refused.** For example, a partner restricted to some ledgers cannot list all the ledgers of the organization.
* **A partner with applications cannot be deleted.** Delete its applications first. To pause a partner instead, suspend it. Suspension is reversible; deletion is not.
* **A partner's own IP allowlist replaces your tenant's list.** It does not add to it. An address that is only on your tenant's list does not work for that partner. The partner's list applies even when your tenant's list is off.
## Products that accept partners
***
Each product declares, in its permission manifest, which restrictions it accepts: for example organization, ledger, account, portfolio, or segment. Today Midaz (the ledger) and Tracer accept partners. Midaz requires one organization for every partner and accepts optional restrictions on ledgers, accounts, account aliases, assets, portfolios, segments, holders, and other items. Tracer accepts optional restrictions on rules, limits, transaction validations, accounts, portfolios, segments, and merchants.
## Next steps
***
Create a partner step by step, issue its credentials, suspend it, or delete it.
The partner operations, their fields, examples, and error codes.
The tenant list that a partner without a list of its own uses.
Every code Access Manager can return.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.