Create a partner

curl --request POST \
  --url https://api.example.com/v1/partners \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "displayName": "Loja do Zé",
  "permissions": [
    {
      "actions": [
        "get",
        "post"
      ],
      "product": "midaz",
      "resources": [
        "accounts",
        "balances"
      ]
    }
  ],
  "ipAllowlist": [
    {
      "cidr": "203.0.113.0/24",
      "description": "Loja do Zé — SP datacenter"
    }
  ],
  "scope": [
    {
      "field": "ledgerId",
      "product": "midaz",
      "values": [
        "00000000-0000-0000-0000-000000000000"
      ]
    }
  ],
  "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"

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

	req, _ := http.NewRequest("POST", 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: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    displayName: 'Loja do Zé',
    permissions: [
      {
        actions: ['get', 'post'],
        product: 'midaz',
        resources: ['accounts', 'balances']
      }
    ],
    ipAllowlist: [{cidr: '203.0.113.0/24', description: 'Loja do Zé — SP datacenter'}],
    scope: [
      {
        field: 'ledgerId',
        product: 'midaz',
        values: ['00000000-0000-0000-0000-000000000000']
      }
    ],
    validFrom: '2026-01-01T00:00:00Z',
    validUntil: '2027-01-01T00:00:00Z'
  })
};

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

import requests

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

payload = {
    "displayName": "Loja do Zé",
    "permissions": [
        {
            "actions": ["get", "post"],
            "product": "midaz",
            "resources": ["accounts", "balances"]
        }
    ],
    "ipAllowlist": [
        {
            "cidr": "203.0.113.0/24",
            "description": "Loja do Zé — SP datacenter"
        }
    ],
    "scope": [
        {
            "field": "ledgerId",
            "product": "midaz",
            "values": ["00000000-0000-0000-0000-000000000000"]
        }
    ],
    "validFrom": "2026-01-01T00:00:00Z",
    "validUntil": "2027-01-01T00:00:00Z"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(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"
  }
}

Create a partner

Registers one of your customers as a partner and fixes, up front, everything its future credentials will be allowed to reach: permissions says WHAT it may do in each product (collections × verbs) and scope says WHERE (which organization, which ledgers). The two are combined with AND at every request, so a partner reaches only the intersection.

This is the FIRST call in the flow. Nothing is issued here — no credential, no secret. Once the partner exists you create M2M applications against it with POST /v1/applications { "partnerId": "<the id returned here>" }, one per product, and hand the resulting clientId/clientSecret to the customer. A partner with no application is inert.

On success a new record is created in YOUR organization (resolved from your token — there is no tenant field to send) with a server-generated UUID id, state active, and the exact permissions, scope, validity window and IP allowlist you supplied. Nothing in any product changes: the scope values are recorded, never verified against the product and never created there.

Failures, all as RFC 9457 problem documents whose code member carries the identifier below:

400 IDE-1042 — a scope field is not one the product’s published scope catalog declares, or the product publishes no catalog at all. GET /v1/scope-catalog/{product} lists the accepted dimensions; the message names the offending field.
400 IDE-0001 (scope) — the product’s catalog marks a dimension required and the scope has no line for it.
400 IDE-0002 (scope) — several values on a dimension the catalog does not mark multi.
400 IDE-1043 — a permission asks for a resource, an action, or a resource/action pair that no ONE enabled permission bound to your organization’s <product>-editor-role holds, or that role holds nothing in the product. That is the ceiling; you cannot delegate more than you hold. Each permission of the role counts on its own: a pair is allowed only when one permission holds both its resource and its action, so a verb held for one resource is never borrowed by another. The message names the offending resource, action or pair; drop it from the line, or have it granted to the editor role first.
400 IDE-1054 — a permission names a product that is not ready for partners yet: it has not published a scope catalog, so a partner could not be narrowed to any of its instances. The message names the offending permissions[i].product; remove that line.
400 IDE-1055 — a permission names a product that has a scope catalog but has not opted in to partners (its manifest does not declare partners: true; GET /v1/scope-catalog/{product} shows partners: false). Nothing in your request can change that: remove the line, or wait for the product to publish the opt-in. errors[0].location is body.permissions[i].product.
400 IDE-1056 — a permission grants a write (post, put, patch, delete) that the product performs at a level wider than the partner’s scope: a partner confined to one ledger cannot be granted creating ledgers, which acts on the whole organization. The product’s levels are in GET /v1/scope-catalog/{product} (levels). Remove that action, or scope the partner at the level the write needs. errors[0].location is body.permissions[i]; nothing is written.
400 IDE-1052 — any other refusal of the identity provider; the message repeats its code and sentence.
400 IDE-1044 — a product appears in scope but not in permissions, which would authorize nothing.
400 IDE-1045 — validUntil is not later than validFrom.
400 IDE-1047 — "*" was used in permissions.resources or permissions.actions. A wildcard means allow-all and is refused; list the values.
400 IDE-1048 — ipAllowlist is an empty array. Omit it or send null to inherit the organization’s list.
400 IDE-0036 / 400 IDE-1050 — an ipAllowlist entry has an unparseable cidr, or the same network appears twice.
400 IDE-0001 — a required member is missing; the errors list names it.
409 IDE-1040 — displayName is already used by another partner of yours.
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.

POST

partners

Create a partner

curl --request POST \
  --url https://api.example.com/v1/partners \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "displayName": "Loja do Zé",
  "permissions": [
    {
      "actions": [
        "get",
        "post"
      ],
      "product": "midaz",
      "resources": [
        "accounts",
        "balances"
      ]
    }
  ],
  "ipAllowlist": [
    {
      "cidr": "203.0.113.0/24",
      "description": "Loja do Zé — SP datacenter"
    }
  ],
  "scope": [
    {
      "field": "ledgerId",
      "product": "midaz",
      "values": [
        "00000000-0000-0000-0000-000000000000"
      ]
    }
  ],
  "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"

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

	req, _ := http.NewRequest("POST", 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: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    displayName: 'Loja do Zé',
    permissions: [
      {
        actions: ['get', 'post'],
        product: 'midaz',
        resources: ['accounts', 'balances']
      }
    ],
    ipAllowlist: [{cidr: '203.0.113.0/24', description: 'Loja do Zé — SP datacenter'}],
    scope: [
      {
        field: 'ledgerId',
        product: 'midaz',
        values: ['00000000-0000-0000-0000-000000000000']
      }
    ],
    validFrom: '2026-01-01T00:00:00Z',
    validUntil: '2027-01-01T00:00:00Z'
  })
};

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

import requests

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

payload = {
    "displayName": "Loja do Zé",
    "permissions": [
        {
            "actions": ["get", "post"],
            "product": "midaz",
            "resources": ["accounts", "balances"]
        }
    ],
    "ipAllowlist": [
        {
            "cidr": "203.0.113.0/24",
            "description": "Loja do Zé — SP datacenter"
        }
    ],
    "scope": [
        {
            "field": "ledgerId",
            "product": "midaz",
            "values": ["00000000-0000-0000-0000-000000000000"]
        }
    ],
    "validFrom": "2026-01-01T00:00:00Z",
    "validUntil": "2027-01-01T00:00:00Z"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(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"
  }
}

Autorizaciones

Authorization

string

header

requerido

JWT bearer token issued by the identity provider.

Cuerpo

application/json

The partner to create.

displayName

string

requerido

Human-readable name for the partner, unique within the organization (a duplicate is refused with IDE-1040). 1-128 characters after trimming. This is NOT the id: the id is a server-generated UUID returned in the response.

Required string length: 1 - 128

Ejemplo:

"Loja do Zé"

permissions

object[] | null

requerido

What the partner may do, per product. A product with no entry here is unreachable by the partner, whatever its scope says.

Show child attributes

ipAllowlist

object[] | null

The partner's own IP allowlist. Omit it or send null to inherit the organization's list — for a partner "no list" means INHERIT, never "allow everything". An empty array is refused (IDE-1048).

Show child attributes

scope

object[] | null

Where the partner may do it, per product and dimension. Optional as a whole; when a product's published scope catalog marks a dimension required and that product is scoped, the entry for that dimension is mandatory.

Show child attributes

validFrom

string<date-time>

RFC 3339 instant before which the partner's credentials are not honoured. Absent means "valid immediately".

Ejemplo:

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

validUntil

string<date-time>

RFC 3339 instant after which the partner's credentials stop being honoured (the authorize call answers authorized=false with reason "expired", which the calling product turns into 401). Absent means "no end date". Must be later than validFrom, else IDE-1045.

Ejemplo:

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

Respuesta

Created

applicationsCount

integer<int64>

requerido

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

Ejemplo:

2

createdAt

string

requerido

When the partner was created (RFC 3339).

Ejemplo:

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

displayName

string

requerido

Human-readable name, unique within the organization.

Ejemplo:

"Loja do Zé"

string

requerido

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.

Ejemplo:

"00000000-0000-0000-0000-000000000000"

ipAllowlist

object[] | null

requerido

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

requerido

What the partner may do, per product.

Show child attributes

scope

object[] | null

requerido

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>

requerido

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.

Opciones disponibles:

active,

suspended

Ejemplo:

"active"

updatedAt

string

requerido

When it was last modified (RFC 3339).

Ejemplo:

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

validFrom

string<date-time> | null

requerido

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

Ejemplo:

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

validUntil

string<date-time> | null

requerido

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.

Ejemplo:

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

Resumen

Autenticación

Autorización

Información del usuario

MFA de inicio de sesión

Resumen de identidad

Grupos

Aplicaciones

Socios

Usuarios

MFA de cuenta

Proveedores de identidad

Proveedores de aplicaciones

Permisos

Roles

Políticas de seguridad

Declaraciones de plugins

Manejo de errores

Create a partner

Autorizaciones

Cuerpo

Respuesta