Returns how the caller holds one Role, and so whether an endpoint that needs it would let the caller in.
For a system Role, use SYS as BANK_ID: it then means no bank. A bank Role is looked up at
BANK_ID, where SYS is the system space of Dynamic Entities.
Use it from a service that receives an OBP-API token (for example API Explorer II, the Portal or API Manager)
and must decide, as OBP-API would, whether that token may see something the service guards with an OBP Role.
caller: the User and Consumer of the token. application_only is true when the application is acting as
itself. That means its Consumer is a Platform App, and it calls with no User or as its own User. A
client-credentials token brings that User, named after the Consumer's client id.
held_by.user: the User holds the Role as an Entitlement, or as a virtual Role from super_admin_user_ids or
oidc_operator_user_ids.
held_by.consumer: the Consumer holds the Role as a Scope.
scopes_required: the props require_scopes_for_all_roles or require_scopes_for_listed_roles say that
a person also needs the Role as a Scope on the Consumer they call through.
allowed: an endpoint that needs this Role would let the caller in. An application acting as itself needs
the Scope. A person needs the Entitlement, and also the Scope when scopes_required is true. A virtual Role
is always allowed. An endpoint that accepts several Roles lets the caller in if any one of them is allowed.
Just-in-time Entitlements (create_just_in_time_entitlements) are not granted here: an endpoint may still
grant one when it is called.
No Role is required: a caller may always learn what it holds. The caller must be identifiable as a Consumer.
An unknown Role name gets 404.
User Authentication is Optional. The User need not be logged in.
Application Access is Required. The Application must be authenticated.