> ## 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 in TED Lerian

> Confine a partner's TED Lerian credential to the Midaz organization and ledger of your installation, name them on every request, and read the refusals it receives.

A [partner](https://docs.lerian.studio/en/platform/access-manager/features/partners/overview) can call TED Lerian with its own credential. You confine that credential to the Midaz organization and, if you want, to the ledger that TED Lerian works on. This page is about TED Lerian. For TED JD, see [Partners in TED](https://docs.lerian.studio/en/platform/access-manager/features/partners/ted.md).

Every TED Lerian partner needs a scope.

> [!NOTE]
>
> You need Access Manager v3.20.0 or later. Earlier versions do not accept the permissions of TED Lerian.

## Step by step

***

**1. Choose where the partner acts**

TED Lerian has two restrictions. Both apply to the resources `transfers` and `incoming-transfers`:

| Restriction | API field | What the partner reaches | What it is refused |
| - | - | - | - |
| **Midaz organization** | `organizationId` | Send a TED and get a fee quote, read and list transfers and their timelines, cancel a transfer, and read and list incoming TEDs and their timelines. | Every other organization, and the routes that act on the whole tenant (see [Routes that no partner reaches](#routes-that-no-partner-reaches)). |
| **Midaz ledger** | `ledgerId` | Send a TED and get a fee quote. The ledger sits under the organization. | Every other ledger. Also the reads, the cancellation, and the incoming TEDs (see [The ledger restriction covers only sending](#the-ledger-restriction-covers-only-sending)). |

TED Lerian works on one organization and one ledger: the ones configured for your institution. See the setup in [TED Lerian API overview](https://docs.lerian.studio/en/reference/interfaces/ted-lerian/ted-lerian-api-overview.md). Put that organization, and that ledger if you restrict by ledger, in the partner's scope.

**2. Give the partner its permissions and scope**

Create the partner, or change it, in the [Console](https://docs.lerian.studio/en/platform/access-manager/features/partners/console.md) or with the [Identity API](https://docs.lerian.studio/en/platform/access-manager/features/partners/api.md). The product slug is `plugin-br-ted-lerian`.

* Add the scope entry for the organization. Without a scope entry, Access Manager refuses the partner with `400` and `IDE-1060`.
* To confine the partner to a ledger, also add the scope entry for the ledger.
* Check the resources and actions. The most you can give is what the editor role of TED Lerian holds in your tenant. Above that, Access Manager refuses with `IDE-1043`.

A partner can have only these permissions:

| Permission | Routes | Partner confined to the organization | Partner confined to a ledger |
| - | - | - | - |
| `transfers:create` | `POST /v1/transfers`, `POST /v1/transfers/fee-quotes` | Yes | Yes |
| `transfers:read` | `GET /v1/transfers`, `GET /v1/transfers/{transferId}`, `GET /v1/transfers/{transferId}/timeline` | Yes | No |
| `transfers:cancel` | `POST /v1/transfers/{transferId}/cancel` | Yes | No |
| `incoming-transfers:read` | `GET /v1/incoming-transfers`, `GET /v1/incoming-transfers/{incomingTransferId}`, `GET /v1/incoming-transfers/{incomingTransferId}/timeline` | Yes | No |

Access Manager refuses every other permission with `400` and `IDE-1056`. These permissions act on the whole tenant: the unblock and the fraud analysis decision of a transfer, the return and the decisions on an incoming TED, the reconciliation, the dashboards, the policy and the ISPB bindings, the participants list, the event catalog, and the runtime settings. Access Manager also refuses with `IDE-1056` the permissions marked **No** for a partner confined to a ledger. The Console marks these lines **Outside the scope**.

**3. Create its TED Lerian application**

Create the partner's application with the product `plugin-br-ted-lerian`. See [Create the partner's applications](https://docs.lerian.studio/en/platform/access-manager/features/partners/api.md#create-the-partners-applications) in the API guide, or [in the Console](https://docs.lerian.studio/en/platform/access-manager/features/partners/console.md#create-the-partners-applications). Send the client ID and the client secret to the partner through a secure channel.

**4. Name the organization and the ledger on every request**

The partner names the organization in the `X-Organization-Id` header, and the ledger in the `X-Ledger-Id` header. Both headers are optional for other callers. A partner must send them as this table shows. A request without them is refused.

| Routes | `X-Organization-Id` | `X-Ledger-Id` |
| - | - | - |
| Send and fee quote: `POST /v1/transfers`, `POST /v1/transfers/fee-quotes` | Always | When the partner is confined to a ledger |
| Transfers: `GET /v1/transfers`, `GET /v1/transfers/{transferId}`, `GET /v1/transfers/{transferId}/timeline`, `POST /v1/transfers/{transferId}/cancel` | Always | Not read |
| Incoming TEDs: `GET /v1/incoming-transfers`, `GET /v1/incoming-transfers/{incomingTransferId}`, `GET /v1/incoming-transfers/{incomingTransferId}/timeline` | Always | Not read |

The headers do not choose the organization or the ledger. TED Lerian always takes them from its configuration, and the headers only confirm them. TED Lerian checks each header it reads:

| Header | Answer |
| - | - |
| Absent | The request runs as it does without partners. |
| Same as the configuration | The request runs. |
| Another value, or not a UUID | `400` with `TED-0001`. The message names the header. |
| Present, and the configuration does not have the value | `503` with `TED-0080`. |

This check applies to every caller, also to the applications of your own institution.

When a send or a fee quote has `X-Ledger-Id`, the account in `X-Account-Id` must be an account of that ledger. Otherwise the answer is `400` with `TED-0001`. TED Lerian also does this check on a retry with an `X-Idempotency` key that it already used. It does not replay a stored answer for an account of another ledger.

**5. Confirm that it works**

Use the credential of a partner with `transfers:read`, confined to the organization only. List the transfers of the organization in the partner's scope. The answer is `200`:

```bash theme={null}
TED_LERIAN_BASE_URL="https://ted-lerian.<your-domain>"     # your TED Lerian base URL
TED_LERIAN_BEARER_TOKEN="paste-the-partner-access-token-here"
MIDAZ_ORGANIZATION_ID="paste-the-organization-in-the-scope"

curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer ${TED_LERIAN_BEARER_TOKEN}" \
  -H "X-Organization-Id: ${MIDAZ_ORGANIZATION_ID}" \
  "${TED_LERIAN_BASE_URL}/v1/transfers"
```

Send the same request without the `X-Organization-Id` header. The answer is `403` with `TED-0071`.

## The ledger restriction covers only sending

***

TED Lerian reads the ledger only when a partner sends a TED or gets a fee quote. The reads, the cancellation, and the incoming TEDs carry no ledger. A transfer can sit on an earlier ledger of your institution, and an incoming TED can sit on any ledger of the ISPB bindings. TED Lerian does not filter them by ledger.

So a partner confined to a ledger can only send and get fee quotes. Access Manager refuses to give it `transfers:read`, `transfers:cancel`, or `incoming-transfers:read`, with `400` and `IDE-1056`. To let a partner read or cancel transfers, confine it to the organization only.

A partner confined to the organization reads all the transfers and incoming TEDs of the organization, on every ledger. Give it `transfers:read` and `incoming-transfers:read` only when it can see all of them.

## Incoming TEDs without an organization

***

TED Lerian attributes each incoming TED to an organization. An incoming TED that it cannot attribute yet has no organization, and it waits in `MANUAL_REVIEW`. A partner does not see these incoming TEDs:

* `GET /v1/incoming-transfers` does not list them.
* `GET /v1/incoming-transfers/{incomingTransferId}` and `GET /v1/incoming-transfers/{incomingTransferId}/timeline` answer `404`, as if the TED did not exist.

The applications of your institution still see these incoming TEDs when they do not act for a partner. Use one of them to review the incoming TEDs that have no organization.

## The partner's Midaz rules do not apply to its transfers

***

TED Lerian calls Midaz and the CRM with its own credential, also when it serves a partner. The partner's Midaz permissions and scope do not apply to these calls.

TED Lerian has no account restriction. The account in `X-Account-Id` must belong to the organization of TED Lerian, or the answer is `403` with `TED-0009`. When the request has `X-Ledger-Id`, the account must also be an account of that ledger, or the answer is `400` with `TED-0001`.

> [!WARNING]
>
> Give `transfers:create` only to a partner that can send from every account of the organization. A partner with this permission can send from any account of the organization that it names in `X-Account-Id`.

## Routes that no partner reaches

***

Every route outside the table of step 2 acts on the whole tenant. A partner cannot have the permissions of these routes, so TED Lerian refuses it with `403` and `TED-0071`:

* The unblock and the fraud analysis decision of a transfer.
* The return, the review decision, and the fraud check decision of an incoming TED.
* The reconciliation routes, `/v1/reconciliation/*`.
* The operations dashboards, `/v1/operations/*`.
* The policy and the ISPB bindings, `/v1/policy/*`.
* The participants list, `GET /v1/participants`.
* The runtime settings, `/v1/system/*`.

Use an application of your own institution for these routes.

## If something fails

***

| Code | Status | What it means | What to do |
| - | - | - | - |
| `TED-0071` | 403 | The request names an organization or a ledger outside the partner's scope, or does not send a header the partner must send. It is also outside the partner's permissions or IP allowlist. | Send `X-Organization-Id`, and `X-Ledger-Id` when the partner is confined to a ledger, with values in the partner's scope. Check also the partner's permissions and IP allowlist. |
| `TED-0070` | 401 | The partner is suspended, or the request is outside its validity window. | Reactivate the partner, or change its validity window. |
| `TED-0001` | 400 | `X-Organization-Id` or `X-Ledger-Id` is not a UUID, or names another organization or ledger than the configuration of TED Lerian. On a send or a fee quote, the account in `X-Account-Id` is not an account of the ledger in `X-Ledger-Id`. | Send the organization and the ledger that TED Lerian is configured for. A caller that is not a partner can also leave out the header. Debit an account of that ledger. |
| `TED-0080` | 503 | The request sends a header, and TED Lerian has no organization or ledger configured to compare it with. | The administrator configures the organization and the ledger of TED Lerian. |

`TED-0071` does not say whether the permissions or the scope refused the request. This is on purpose: a partner cannot use a refusal to learn which organizations or ledgers exist outside its scope.

A change to a partner, such as a suspension or a new scope, applies on its next request, also with a token it already has. When TED Lerian keeps the Access Manager decisions for a time, set in `AUTH_CACHE_TTL`, the change applies after that time.

For every other code, see the [TED Lerian error list](https://docs.lerian.studio/en/reference/interfaces/ted-lerian/ted-lerian-error-list.md). For the refusals when you create or change a partner, see [Error codes](https://docs.lerian.studio/en/platform/access-manager/features/partners/api.md#error-codes) in the API guide.


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