Enforce a user permission

Enforces a permission for the Bearer token subject against a resource and action. A denied permission is returned as 200 with authorized=false, not 403. A 403 means the caller IP is outside the IP allowlist (AUT-0021). A token whose credential no longer resolves is answered 401, not a server error, and retrying will not help: AUT-1011 when its application was deleted, AUT-1012 when the partner it belongs to was. When a Lerian product that serves a partner’s request calls another and sends the partner’s token as actorToken, the request is authorized only when both tokens are, and a refusal by the partner is still a 200 with authorized=false and a reason starting with actor_. A partner granted nothing in the product is checked only for its credential, tenant, state and validity window, and its IP allowlist is not applied on this call. When the authorization server cannot be reached, is too slow to answer, or is failing, the answer is 503 AUT-0033: nothing about the request was wrong, and it may be retried later.

POST /v1/authorize

Enforce a user permission

cURL

curl --request POST \
  --url https://auth.sandbox.lerian.net/v1/authorize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "action": "post",
  "resource": "ledger",
  "actorToken": "<string>",
  "attributes": {
    "organizationId": "00000000-0000-0000-0000-000000000000"
  },
  "clientIp": "203.0.113.7",
  "product": "midaz",
  "sub": "admin/ledger-editor-role"
}
'

200

{
  "authorized": true,
  "timestamp": "2024-01-15T09:30:00Z",
  "reason": "scope"
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Headers

Authorization · string

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

Body

application/json

action · string · required

The operation being performed on the resource.

Example:

"post"

resource · string · required

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

Example:

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

Show child attributes

Example:

{
  "organizationId": "00000000-0000-0000-0000-000000000000"
}

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.

Example:

"203.0.113.7"

product · string

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

Example:

"midaz"

sub · string

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

Example:

"admin/ledger-editor-role"

Response

200

application/json

OK

authorized · boolean · required

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

Example:

true

timestamp · string<date-time> · required

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

Example:

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

Available options: permission, scope, suspended, expired, actor_tenant, actor_invalid, actor_permission, actor_scope, actor_suspended, actor_expired

Example:

"scope"