> ## 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. # 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": "" }`, 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 `-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. ## OpenAPI ````yaml /pt/openapi/v3-current/AM-identity.yaml post /v1/partners openapi: 3.1.0 info: contact: name: Lerian Studio url: https://lerian.studio description: >- OpenAPI 3.1 surface for the plugin-access-manager identity component. It exposes the M2M-gated declarations upsert (PUT /v1/declarations/{slug}), through which each plugin declares its own permissions/roles/M2M contract, and partner management (/v1/partners), through which a tenant administrator grants its own customers scoped API credentials. The remaining identity routes stay Fiber-native and are described by the separate OAS 2 document in the same folder. license: name: Apache-2.0 url: https://www.apache.org/licenses/LICENSE-2.0 title: Plugin Access Manager — Identity API version: v1 servers: [] security: [] tags: - description: >- M2M-only: each plugin declares its own permissions, roles and M2M contract, and the server reconciles them. name: Declarations - description: >- A tenant administrator's customers. Each partner holds what its credentials may DO (permissions, per product) and WHERE they may do it (scope, per product and dimension); an M2M application attached to one is confined to that intersection. Administrator-only: authorized on the "partners" resource, and every route resolves the owning organization from the caller's token. name: Partners paths: /v1/partners: post: tags: - Partners summary: Create a partner description: >- 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": "" }`, 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 `-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. operationId: createPartner requestBody: content: application/json: schema: $ref: '#/components/schemas/PartnerInput' description: The partner to create. required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/PartnerResponse' description: Created '422': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Internal Server Error '503': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Service Unavailable default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error security: - BearerAuth: [] components: schemas: PartnerInput: additionalProperties: false properties: displayName: description: >- 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. examples: - Loja do Zé maxLength: 128 minLength: 1 type: string ipAllowlist: description: >- 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). items: $ref: '#/components/schemas/IPAllowlistEntry' type: - array - 'null' permissions: description: >- What the partner may do, per product. A product with no entry here is unreachable by the partner, whatever its scope says. items: $ref: '#/components/schemas/PartnerPermission' type: - array - 'null' scope: description: >- 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. items: $ref: '#/components/schemas/PartnerScope' type: - array - 'null' validFrom: description: >- RFC 3339 instant before which the partner's credentials are not honoured. Absent means "valid immediately". examples: - '2026-01-01T00:00:00Z' format: date-time type: string validUntil: description: >- 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. examples: - '2027-01-01T00:00:00Z' format: date-time type: string required: - displayName - permissions type: object PartnerResponse: additionalProperties: false properties: applicationsCount: description: >- How many M2M applications are currently attached to this partner. A non-zero value is what makes DELETE answer 409 (IDE-1049). examples: - 2 format: int64 type: integer createdAt: description: When the partner was created (RFC 3339). examples: - '2026-01-15T09:30:00Z' type: string displayName: description: Human-readable name, unique within the organization. examples: - Loja do Zé type: string id: description: >- 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. examples: - 00000000-0000-0000-0000-000000000000 type: string ipAllowlist: description: >- 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. items: $ref: '#/components/schemas/IPAllowlistEntry' type: - array - 'null' permissions: description: What the partner may do, per product. items: $ref: '#/components/schemas/PartnerPermission' type: - array - 'null' scope: description: >- Where the partner may do it, per product and dimension. An empty list means the partner is not restricted by instance in any product. items: $ref: '#/components/schemas/PartnerScope' type: - array - 'null' state: description: >- 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. enum: - active - suspended examples: - active type: string updatedAt: description: When it was last modified (RFC 3339). examples: - '2026-01-15T09:30:00Z' type: string validFrom: description: >- Start of the validity window (RFC 3339), or null when it is open-ended. examples: - '2026-01-01T00:00:00Z' format: date-time type: - string - 'null' validUntil: description: >- 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. examples: - '2027-01-01T00:00:00Z' format: date-time type: - string - 'null' required: - id - displayName - state - permissions - scope - ipAllowlist - validFrom - validUntil - applicationsCount - createdAt - updatedAt type: object Detail: additionalProperties: true properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object IPAllowlistEntry: additionalProperties: false properties: cidr: description: >- Network in CIDR form, or a bare IPv4/IPv6 address which is widened to a host route (/32, /128) on persist. Malformed entries are refused with IDE-0036; the same cidr twice with IDE-1050. examples: - 203.0.113.0/24 type: string description: description: >- Free-text label for this entry, shown to operators. Never influences an access decision; bounded only by length. examples: - Loja do Zé — SP datacenter type: string required: - cidr type: object PartnerPermission: additionalProperties: false properties: actions: description: >- Verbs the partner may use on those collections, lowercase ("get", "post", "patch", "delete"). "head" is granted together with "get". Each resource/action pair must be held by one permission of your organization's editor role in the product, else IDE-1043. "*" is refused (IDE-1047). examples: - - get - post items: type: string type: - array - 'null' product: description: >- Product slug these permissions apply to, as returned by GET /v1/applications/available. Matched by exact equality; a product your organization's editor role holds nothing in is refused with IDE-1043. examples: - midaz type: string resources: description: >- Collections the partner may reach in this product, named exactly as the product declares them ("accounts", "transactions"). Each resource/action pair must be held by one permission of your organization's editor role in the product, else IDE-1043. "*" is refused (IDE-1047). examples: - - accounts - balances items: type: string type: - array - 'null' required: - product - resources - actions type: object PartnerScope: additionalProperties: false properties: field: description: >- Dimension being scoped, as the product's published scope catalog names it (GET /v1/scope-catalog/{product}). A field the catalog does not declare, or any scope line for a product that publishes no catalog, is refused with IDE-1042; a required dimension left out with IDE-0001; several values on a single-valued dimension with IDE-0002. examples: - ledgerId type: string product: description: >- Product slug this scope applies to. Must also appear in permissions, else IDE-1044. examples: - midaz type: string values: description: >- Instance identifiers for this dimension, as UUIDs. Validated for format and field membership only — existence inside the product is NOT checked, so supply values the product's own list API returned. examples: - - 00000000-0000-0000-0000-000000000000 items: type: string type: - array - 'null' required: - product - field - values type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.