Stitch API

5.5. Scopes and Permissions

Stitch uses OAuth 2.0 scopes to model permissions in the API. This means that authorization requests to Stitch SSO will include a list of requested scopes that will be presented to users.


Stitch aims to be respectful of user privacy. That is why end users can opt out of the permissions they do not yet feel comfortable granting a client application.

What scopes are required for my query?

The Stitch IDE includes an interactive schema explorer found under the Docs tab.

The description of each field, type, and union inside the docs includes an automatically generated description of what scopes are needed to access a given piece of data.

An important thing to note is that scopes are recursively enforced. For example, the BankAccount type requires the accounts scope, while the availableBalance field requires the balances scope.

Therefore, to access the availableBalance field, both the accounts and balances scopes would be required.

Try then Ask

Of course if you're not careful, handling all the different permutations of scope sets can greatly complicate your application architecture.

Stitch recommends rather than attempting to reason about scopes up-front, you should instead adopt a model where you first attempt to resolve a query, and then should additional scopes be required, ask for elevated permissions.

The error handling section of the docs briefly showed an example of where a query was attempted that needed the balances scope, but the user had not yet granted it.

This resulted in the following response:

2 "errors": [
3 {
4 "message": "Token is missing the following scope: balances",
5 "locations": [
6 {
7 "line": 6,
8 "column": 7
9 }
10 ],
11 "path": [
12 "node",
13 "currentBalance"
14 ],
15 "extensions": {
16 "code": "FORBIDDEN",
17 "missingScopes": ["balances"]
18 }
19 }
20 ],
21 "data": {
22 "node": {
23 "id": "YWNjb3VudC9mbmIvMjUwNjU1LzYyNDI1MjM5NDcx",
24 "name": "FNB Premier Cheque Account",
25 "currentBalance": null
26 }
27 }

As can be seen in the errors array, the missing scopes for the currentBalance field are found under extensions.missingScopes. This machine-readable representation of the error allows you to programmatically request elevated permissions.

Note that a given field or type may require more than one scope, and more than one field may produce a FORBIDDEN error in a given query.