Update a partner

curl --request PATCH \
  --url https://api.example.com/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"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/partners/{id}"

	payload := strings.NewReader("{\n  \"displayName\": \"Loja do Zé Matriz\",\n  \"ipAllowlist\": [\n    {\n      \"cidr\": \"203.0.113.0/24\",\n      \"description\": \"Loja do Zé — SP datacenter\"\n    }\n  ],\n  \"permissions\": [\n    {\n      \"actions\": [\n        \"get\",\n        \"post\"\n      ],\n      \"product\": \"midaz\",\n      \"resources\": [\n        \"accounts\",\n        \"balances\"\n      ]\n    }\n  ],\n  \"scope\": [\n    {\n      \"field\": \"ledgerId\",\n      \"product\": \"midaz\",\n      \"values\": [\n        \"00000000-0000-0000-0000-000000000000\"\n      ]\n    }\n  ],\n  \"state\": \"suspended\",\n  \"validFrom\": \"2026-01-01T00:00:00Z\",\n  \"validUntil\": \"2027-01-01T00:00:00Z\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
  })
};

fetch('https://api.example.com/v1/partners/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/partners/{id}"

payload = {
    "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"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

{
  "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"
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

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. Access tokens already issued to this partner are NOT revoked — a suspension or a narrowed scope takes effect on the next authorization decision and on the next token issuance, so a token in flight keeps its old rights until it expires. To cut a partner off immediately, delete its applications.

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.
400 IDE-0002 — state is neither active nor suspended. Note there is no expired state: expiry is derived from validUntil at decision time.
404 IDE-1046 — no such partner in your organization.
403 — your token does not hold the partners resource.
503 IDE-0060 — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.
501 IDE-1051 — this deployment publishes the contract but does not serve it yet.

PATCH

partners

{id}

Update a partner

curl --request PATCH \
  --url https://api.example.com/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"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/partners/{id}"

	payload := strings.NewReader("{\n  \"displayName\": \"Loja do Zé Matriz\",\n  \"ipAllowlist\": [\n    {\n      \"cidr\": \"203.0.113.0/24\",\n      \"description\": \"Loja do Zé — SP datacenter\"\n    }\n  ],\n  \"permissions\": [\n    {\n      \"actions\": [\n        \"get\",\n        \"post\"\n      ],\n      \"product\": \"midaz\",\n      \"resources\": [\n        \"accounts\",\n        \"balances\"\n      ]\n    }\n  ],\n  \"scope\": [\n    {\n      \"field\": \"ledgerId\",\n      \"product\": \"midaz\",\n      \"values\": [\n        \"00000000-0000-0000-0000-000000000000\"\n      ]\n    }\n  ],\n  \"state\": \"suspended\",\n  \"validFrom\": \"2026-01-01T00:00:00Z\",\n  \"validUntil\": \"2027-01-01T00:00:00Z\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
  })
};

fetch('https://api.example.com/v1/partners/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/partners/{id}"

payload = {
    "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"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

{
  "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"
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Authorizations

Authorization

string

header

required

JWT bearer token issued by the identity provider.

Path Parameters

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).

Required string length: 1 - 128

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. Suspending takes effect on the next authorization and on the next token issuance — an access token already issued keeps working until it expires.

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

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é"

string

required

Server-generated identifier of the partner (UUID). This is the value to pass as partnerId when creating an application, and the value that travels in the credential's partner claim.

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. An empty list means the partner is not restricted by instance in any product.

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. A past value means every credential of this partner is already refused.

Example:

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

Overview

Authentication

Authorization

User information

Login MFA

Identity overview

Groups

Applications

Partners

Users

Account MFA

Identity providers

Application providers

Permissions

Roles

Security policies

Plugin declarations

Error handling

Update a partner

Authorizations

Path Parameters

Body

Response