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:TED Lerian works on one organization and one ledger: the ones configured for your institution. See the setup in TED Lerian API overview. 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 or with the Identity API. 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
400andIDE-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.
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 in the API guide, or in the Console. 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.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:
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 Send the same request without the
transfers:read, confined to the organization only. List the transfers of the organization in the partner’s scope. The answer is 200: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-transfersdoes not list them.GET /v1/incoming-transfers/{incomingTransferId}andGET /v1/incoming-transfers/{incomingTransferId}/timelineanswer404, as if the TED did not exist.
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.
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/*.
If something fails
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. For the refusals when you create or change a partner, see Error codes in the API guide.
