Saltar al contenido principal
POST
Enforce a user permission

Autorizaciones

Authorization
string
header
requerido

JWT bearer token issued by the identity provider.

Encabezados

Authorization
string

Bearer access token to enforce. The request is rejected with 401 (AUT-0006) when absent.

Cuerpo

application/json
action
string
requerido

The operation being performed on the resource.

Ejemplo:

"post"

resource
string
requerido

The resource being accessed (e.g. "organizations", "ledgers").

Ejemplo:

"ledger"

actorToken
string

The partner's own access token, exactly as the calling Lerian product received it, sent when that product calls this one while serving a partner's request. The Bearer token then belongs to the calling product, and the request is authorized only when BOTH are: the calling product by its own permissions, and the partner by the rules it was granted for this product. A partner granted nothing in this product is checked here only for its credential, tenant, state and validity window, and the partner's IP allowlist is not applied, since this call comes from the calling product, not from the partner. When the partner refuses, authorized is false and reason starts with "actor_": actor_tenant (the partner belongs to another tenant), actor_suspended or actor_expired (the partner is no longer honoured), actor_invalid (not an active partner credential, or its application or partner was deleted), actor_permission or actor_scope (outside the partner's grant). Optional.

attributes
object

Instance identifiers the calling product extracted from the request being authorized, keyed by the product's declared scope field (midaz: "organizationId", "ledgerId"). Optional and additive: a request without it is decided exactly as before. Consumed only for a credential bound to a partner; accepted and ignored for every other credential.

Ejemplo:
clientIp
string

Originating caller IP forwarded by lib-auth for tenant IP-allowlist enforcement. Optional, and honoured ONLY when the calling service reaches this API from a network the platform declares as its own; from any other caller the field is ignored.

Ejemplo:

"203.0.113.7"

product
string

Product that owns the route, forwarded by lib-auth for user-flow isolation. Optional.

Ejemplo:

"midaz"

resolve
string[] | null

Scope dimensions (catalog field names) the calling product asks this API to fill in from the partner's own scope, for a route that lets a partner leave its own party out of the request. For each one the request does not name, a partner holding exactly one value of it in this product is decided as that value, returned in resolved. It is refused as reason=ambiguous when the partner holds two or more values, and as reason=scope when it holds none, the request also names it in attributes, the product's catalog does not declare it, or the resource is that dimension's own collection or one it covers; a grant that does not hold the action on the resource refuses as reason=permission first. Refused as actor_scope together with actorToken. Consumed only for a credential bound to a partner; accepted and ignored for every other credential, whose answer then carries no resolved. Optional.

Ejemplo:
sub
string

Subject to enforce, forwarded by lib-auth (e.g. "admin/ledger-editor-role" for applications). Optional.

Ejemplo:

"admin/ledger-editor-role"

Respuesta

OK

authorized
boolean
requerido

Whether the subject is authorized for the resource+action. A false value is still returned as HTTP 200, not 403.

Ejemplo:

true

timestamp
string<date-time>
requerido

Server time at which the decision was made (RFC 3339).

Ejemplo:

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

reason
enum<string>

Why the request was denied. Present only when authorized is false and the credential is bound to a partner, or the partner named by actorToken refused (the actor_ values). "suspended" and "expired" mean the partner credential itself is no longer valid and the caller should answer 401; "permission" and "scope" stay the 403 a denial is today and are for logs only — never surface which axis failed to the end caller. "ambiguous" answers a request with resolve: the partner holds two or more values of a dimension it asked resolved, so the request has to name one.

Opciones disponibles:
permission,
scope,
ambiguous,
suspended,
expired,
actor_tenant,
actor_invalid,
actor_permission,
actor_scope,
actor_suspended,
actor_expired
Ejemplo:

"scope"

resolved
object

One value per dimension the request asked in resolve: the partner's single value of it. Present only when authorized is true and the request carried resolve; the calling product acts as this party.

Ejemplo: