Upsert a plugin declaration

Creates or replaces the access-manager declaration for the given plugin slug. Called by the product itself, at start-up, with its own M2M token.

The body has two sections and each is replaced ONLY when present, so a product can publish one without touching the other:

• the ACCESS section — permissions, roles and m2m together (a permission names the roles it grants to, so they are applied as one full sync: what the section no longer declares is removed). Served in single-tenant deployments only; in multi-tenant it answers 501.
• the SCOPE section — scope.dimensions, the dimensions the product’s routes address instances by, and partners, the product’s opt-in to partner credentials (either alone is the section), plus levels in the scope-only form. It replaces the product’s scope catalog wholesale and is served in single- AND multi-tenant deployments: the catalog is global per product. Every partner write is validated against it, and GET /v1/scope-catalog/{product} reads it back.

A body carrying both sections in multi-tenant applies the scope section and then answers 501 for the access section.

Failures: 422 — the manifest is malformed (the message lists every violation), declares neither section, its service is not the slug, no application is registered for the calling client, or the identity provider refused the scope catalog; 403 — the token does not speak for the slug; 409 — the access section could not be persisted; 501 — the access section in a multi-tenant deployment; 503 IDE-0066 — the identity provider is unavailable, retry later; 500 — another dependency failed, retry.

PUT /v1/declarations/{slug}

Upsert a plugin declaration

cURL

curl --request PUT \
  --url https://identity.sandbox.lerian.net/v1/declarations/{slug} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "integrations": [
    "midaz"
  ],
  "levels": [
    {
      "action": "update",
      "level": "organizationId",
      "resource": "ledgers"
    }
  ],
  "m2m": {
    "exposed": true,
    "needs": [
      "midaz"
    ],
    "party_roles": [
      "operator"
    ],
    "roles": [
      "editor"
    ],
    "service_roles": [
      "lender-m2m-role"
    ]
  },
  "partners": true,
  "permissions": [
    {
      "action": "create",
      "effect": "allow",
      "level": "organizationId",
      "resource": "billing-packages",
      "roles": [
        "editor"
      ]
    }
  ],
  "roles": [
    {
      "granted_to": [
        {
          "group": "fees-admins"
        }
      ],
      "name": "editor"
    }
  ],
  "scope": {
    "dimensions": [
      {
        "collection": "ledgers",
        "covers": [
          "balances",
          "operations"
        ],
        "explicit": true,
        "from": "path",
        "label": "ledger",
        "multi": true,
        "name": "ledgerId",
        "param": "ledger_id",
        "parent": "organizationId",
        "required": false
      }
    ]
  },
  "service": "plugin-fees",
  "version": 3
}
'

200

{
  "slug": "plugin-fees",
  "status": "accepted"
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Path Parameters

slug · string · required

Plugin slug that owns the declaration being upserted.

Example:

"plugin-fees"

Body

application/json

Declaration manifest to upsert for the slug.

integrations · string[] | null

Lerian services this product calls while serving a request (e.g. midaz). A partner's request this product relays to one of them is also decided there by the partner's own rules for that service, so the Console offers to set those rules when the partner is granted this product. Forwarded with the scope catalog; alone it is a scope-only body. Entries must be non-empty, unique, different from service and contain no wildcard, compared trimmed and case-insensitively.

Example:

["midaz"]

levels · object[] | null

Scope-only form of the permissions' levels: one entry per permission that declares a level, sent when the permission section is not. Forwarded with the scope catalog. Not accepted next to permissions, which carry their level themselves; alone it is not a section, since it would replace the catalog's dimensions and opt-in with nothing.

Show child attributes

m2m · object

Bilateral machine-to-machine contract: which targets this plugin calls and whether it is callable.

Show child attributes

partners · boolean

Opts the product in to partner credentials: a partner can be granted this product only when it is true. Forwarded with the scope catalog; a body carrying only this member is a scope-only body. Replaces the opt-in whenever the catalog is replaced.

Example:

true

permissions · object[] | null

Permissions declared by the plugin; one entry per (resource, action).

Show child attributes

roles · object[] | null

Roles declared by the plugin. Names may use '/' for hierarchy but must not repeat the service prefix (it is added automatically).

Show child attributes

scope · object

Dimensions the product's routes address instances by — the WHERE a partner's scope lines name. Replaces the product's catalog when present. Accepted in single- and multi-tenant deployments.

Show child attributes

service · string

Service that owns this declaration; matches the caller token (the plugin- prefix is kept).

Example:

"plugin-fees"

version · integer<int64>

Advisory manifest version. Must be a positive integer. Excluded from the canonical content hash.

Example:

3

Response

200

application/json

OK

slug · string · required

Slug of the declaration that was upserted.

Example:

"plugin-fees"

status · string · required

Outcome of the upsert operation.

Example:

"accepted"