API Explorer

API.Entitlements and Scopes

| |A Role can be held in two ways. A User holds it as an Entitlement. A Consumer (an application) holds it as a Scope. When an endpoint needs a Role, who is acting on the request decides which one counts. | |* A person is acting. The Role must be one of the User's Entitlements. The Consumer's Scopes do not count for a person. | |* The Application is acting as itself. The Role must be one of its Consumer's Scopes. The Application counts as acting as itself only if both of these hold: | 1. Its Consumer is a Platform App (see here). | 2. It calls with no User, or as its own User. A client-credentials token brings that User: provider obp-oidc#client (or keycloak#client for a Keycloak service account), named after the client id. | |For example, a person logs in by DirectLogin through a Consumer that holds the Scope CanGetConsumers. They still need their own CanGetConsumers Entitlement. The same Consumer, if it is a Platform App, can call with a client-credentials token and is let in on its Scope. So whoever is let in is also who is recorded as acting. | |A Consumer that is not a Platform App can still hold Scopes. They then work only as a limit on people, as described next. | |Scopes as a limit on people. An installation can set require_scopes_for_all_roles to true, or list the Role in require_scopes_for_listed_roles. A person then needs the Entitlement, and the Consumer they call through needs the Scope. An Application acting as itself still needs only its Scope. | |Who may call an endpoint at all is set by its list of possible errors: | |* OBP-20001 (User not logged in), or a Role: a User is required. |* OBP-20200 (The application cannot be identified) without the first: an identified Application is required, and a User is optional. Payment providers creating Berlin Group and UK Open Banking consents call like this. |* Neither: anyone may call. | |Endpoints used to carry an authMode (UserOnly, ApplicationOnly, UserXORApplication or UserAndApplication). It was removed in November 2026, because who is acting is a fact about each request, not about the endpoint. | |See also: Access Control, Scopes, Roles | |