Scopes & Entitlements
For security purposes, applications and users should only be able to perform actions that they are authorized to do. An application that views transactions should not be able to change the customer’s profile. Similarly, a customer with many accounts may not be allowed to transfer money out of every account, only a select few.
Scopes define which API operations a client application can call. Entitlements define which data an authenticated user can access when performing operations. While these two concepts are similar, scopes only apply to digital applications while entitlements apply to human users.
Scopes
Scopes are the abilities the application is authorized to access. If an application is not authorized to perform an operation, it will never be able to do so regardless of any user entitlements.
If an application is not authorized with a specific scope, the operation fails with a 403 error. For more information on Authorization and Authentication, see ARTICLE.
When a scope is needed to use a function, it is noted in the API documentation. For example, the listAccounts function requires the banking/read scope. This is noted in the API with the note:
This operation requires authentication by one of the following methods:
-
accessToken using scope banking/read
|
Scope |
Description |
Operations |
|---|---|---|
|
profile/read |
Read access to customer and business profile information. |
|
|
profile/write |
Create, write, and delete access to customer and business profile information. |
|
|
banking/read |
Read access to banking data and resources related to customer’s accounts. |
|
|
banking/write |
Read, write, and delete access to banking data and resources related to customer’s accounts. |
|
|
moneyMovement/write |
Create and write access to move money to and from customer’s accounts. |
|
|
data/read |
Read access to other non-account, non-banking, non-profile data, such as financial institution data and settings. |
|
Entitlements
Entitlements are the abilities authenticated users have while using their online bank. For instance, a user may have the ability to make transfers into one financial account, but not make transfers into a different account. The customer is only given the entitlement to make transfers on specific accounts, and will not be able to make a transfer to accounts if they do not have the entitlement for those account.
Entitlement checks often occur in the context of an account or other banking resource, such as a business payment batch. Each entitlement is granted individually to a customer. There is no way to group entitlements together.
The API documentation notes what entitlements are required for API operations. The documentation also covers how to check if the currently authenticated customer has those entitlements. Typically, this is documented in an allows property that contains a permissions schema unique to that resource. For example for an account there is an account.allows property that has an accountPermsisions schema.
Example entitlements may look like:
{ ...{ "approve": false, "edit": false, "submit": true, "delete": false},...}