Update a partner

Changes a partner’s access, its validity window, its IP allowlist or its state. Every member is optional and anything you omit is left alone — but permissions and scope, when supplied, REPLACE the stored list wholesale. There is no per-entry merge, because a merge would make “remove the last ledger” impossible to express.

Called to widen or narrow a partner mid-life, and to suspend or reactivate one (state: "suspended" / "active"). Suspending is the reversible kill switch; deleting is not.

ipAllowlist has THREE meanings here and they are not interchangeable: omit the member to leave the list as it is, send null to go back to inheriting the organization’s list, send entries to replace it with the partner’s own. An empty array is refused.

validFrom and validUntil work the same way, one bound at a time: omit the member to keep the stored bound, send an RFC 3339 instant to set it, send null to remove it and leave the window open on that side (no start date: honoured from now on; no end date: never expires — a partner already past its end date is honoured again unless it is suspended). An empty string is refused with 422. When you send only one bound it is checked against the other one as stored: moving validFrom to or past the stored validUntil, or validUntil to or before the stored validFrom, is 400 IDE-1045 and nothing is written. To move a window to a later period, send both bounds in the same request.

What changes: the stored record, and with it every future authorization. The change takes effect on the next authorization decision, including for access tokens already issued to this partner. Token issuance is refused while the partner is suspended or outside its validity window, and from an address outside its IP allowlist; a permission or scope change does not stop issuance, it limits what the token can do. To cut a partner off, suspend it.

Failures: every code POST can return, applied to the record as it will be after the patch (IDE-1042, IDE-1043, IDE-1044, IDE-1045, IDE-1047, IDE-1048, IDE-0036, IDE-1050, IDE-1052, 409 IDE-1040), plus:

• 400 IDE-1054 — the product is not ready for partners yet: it has not published a scope catalog. Raised only when the request sends permissions: a partner that already holds such a line can still be suspended, reactivated or renamed, and the line can be removed.
• 400 IDE-1055 — a permission names a product that has not opted in to partners. Like IDE-1054 it is raised only when the request sends permissions, for every line; remove the line to proceed.
• 400 IDE-1056 is checked when either permissions or scope changes: granting a write and narrowing the scope under a write already granted both put the write above the scope. Narrow the scope and drop the write in the same update.
• 404 IDE-1046 — no such partner in your organization.
• 403 — your token does not hold the partners resource.
• 503 IDE-0066 — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.

PATCH /v1/partners/{id}

Update a partner

cURL

curl --request PATCH \
  --url https://identity.sandbox.lerian.net/v1/partners/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "displayName": "Loja do Zé Matriz",
  "ipAllowlist": [
    {
      "cidr": "203.0.113.0/24",
      "description": "Loja do Zé — SP datacenter"
    }
  ],
  "permissions": [
    {
      "actions": [
        "get",
        "post"
      ],
      "product": "midaz",
      "resources": [
        "accounts",
        "balances"
      ]
    }
  ],
  "scope": [
    {
      "field": "ledgerId",
      "product": "midaz",
      "values": [
        "00000000-0000-0000-0000-000000000000"
      ]
    }
  ],
  "state": "suspended",
  "validFrom": "2026-01-01T00:00:00Z",
  "validUntil": "2027-01-01T00:00:00Z"
}
'

200

{
  "applicationsCount": 2,
  "createdAt": "2026-01-15T09:30:00Z",
  "displayName": "Loja do Zé",
  "id": "00000000-0000-0000-0000-000000000000",
  "ipAllowlist": [
    {
      "cidr": "203.0.113.0/24",
      "description": "Loja do Zé — SP datacenter"
    }
  ],
  "permissions": [
    {
      "actions": [
        "get",
        "post"
      ],
      "product": "midaz",
      "resources": [
        "accounts",
        "balances"
      ]
    }
  ],
  "scope": [
    {
      "field": "ledgerId",
      "product": "midaz",
      "values": [
        "00000000-0000-0000-0000-000000000000"
      ]
    }
  ],
  "state": "active",
  "updatedAt": "2026-01-15T09:30:00Z",
  "validFrom": "2026-01-01T00:00:00Z",
  "validUntil": "2027-01-01T00:00:00Z"
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Path Parameters

id · string<uuid> · required

Identifier of the partner to modify.

Example:

"00000000-0000-0000-0000-000000000000"

Body

application/json

The members to change. Anything omitted is left as it is.

displayName · string

New human-readable name. Still unique within the organization (IDE-1040).

Minimum string length: 1

Example:

"Loja do Zé Matriz"

ipAllowlist · object[] | null

Omit to leave the list untouched, send null to go back to inheriting the organization's list, send entries to replace it. An empty array is refused (IDE-1048).

Show child attributes

permissions · object[]

Replaces the whole permissions list when supplied.

Show child attributes

scope · object[]

Replaces the whole scope list when supplied.

Show child attributes

state · enum<string>

Suspend or reactivate the partner. Takes effect on the next authorization decision, including for access tokens already issued, and on the next token issuance.

Available options: active, suspended

Example:

"suspended"

validFrom · string<date-time> | null

New window start (RFC 3339). Omit to keep the stored start; send null to remove it, so the partner's credentials are honoured from now on; an empty string is refused (422). The resulting window is checked against the stored validUntil when that is not sent: validUntil must stay later than validFrom, else 400 IDE-1045.

Example:

"2026-01-01T00:00:00Z"

validUntil · string<date-time> | null

New window end (RFC 3339). Omit to keep the stored end; send null to remove it, so the window has no end date and a partner already past its end date is honoured again (unless suspended); an empty string is refused (422). Must be later than validFrom — the one sent, or the stored one when validFrom is not sent — else 400 IDE-1045.

Example:

"2027-01-01T00:00:00Z"

Response

200

application/json

OK

applicationsCount · integer<int64> · required

How many M2M applications are currently attached to this partner. A non-zero value is what makes DELETE answer 409 (IDE-1049).

Example:

2

createdAt · string · required

When the partner was created (RFC 3339).

Example:

"2026-01-15T09:30:00Z"

displayName · string · required

Human-readable name, unique within the organization.

Example:

"Loja do Zé"

id · string · required

Server-generated identifier of the partner (UUID). This is the value to pass as partnerId when creating an application.

Example:

"00000000-0000-0000-0000-000000000000"

ipAllowlist · object[] | null · required

The partner's own IP allowlist, or null when it inherits the organization's list. Null and an empty list are NOT the same thing here: null is inheritance, and an empty own list cannot be stored.

Show child attributes

permissions · object[] | null · required

What the partner may do, per product.

Show child attributes

scope · object[] | null · required

Where the partner may do it, per product and dimension.

Show child attributes

state · enum<string> · required

Whether the partner's credentials are honoured. Note this never reads "expired": expiry is derived from validUntil at decision time, so a closed window shows here as "active" with a past validUntil.

Available options: active, suspended

Example:

"active"

updatedAt · string · required

When it was last modified (RFC 3339).

Example:

"2026-01-15T09:30:00Z"

validFrom · string<date-time> | null · required

Start of the validity window (RFC 3339), or null when it is open-ended.

Example:

"2026-01-01T00:00:00Z"

validUntil · string<date-time> | null · required

End of the validity window (RFC 3339), or null when it is open-ended.

Example:

"2027-01-01T00:00:00Z"