• None
  • Manage Credentials
Launch IDE ↗

Stitch API

4.3. Reauthorization

The previous chapter went over general error handling in the Stitch API.

One error that is imperative to handle, and hence deserved its own chapter is the REAUTHORIZATION_REQUIRED error.

Banks generally have more stringent security policies than most other kinds of applications.

Some banks require that users reauthorize when logging in and even more of them require reauthorization when performing sensitive actions such as increasing limits, adding beneficiaries, or making once off payments.

Reauthorization typically requires that the user perform some form of multifactor authentication (MFA).

Stitch automatically handles MFA when the user initially links their account. However, when making queries after this point, Stitch will eventually need to create a new banking session as bank portals enforce a finite session duration.

Below you can see the standard flow, where no MFA is required:

Stitch API no MFA

Below you can now see the flow, where MFA is required, and a reauthorization needs to be performed:

Stitch API MFA

For the banks that require reauthorization during login, the Stitch API is not able to automatically recreate sessions until the user is again present. This is where REAUTHORIZATION_REQUIRED comes in.

Structure of a reauthorization error

A reauthorization error will look like the JSON response body below:

2 "errors": [
3 {
4 "message": "Reauthorization is required",
5 "locations": [
6 {
7 "line": 2,
8 "column": 3
9 }
10 ],
11 "path": [
12 "node"
13 ],
14 "extensions": {
16 "userInteractionUrl": "",
17 "reauthorizationType": "login",
18 "id": "dWkvNDhhYmZlYTYtY2I1ZC00OGMwLWFjMWUtYzg5ODNjYmFlZTNm"
19 }
20 }
21 ],
22 "data": {
23 "node": null
24 }

As you can see, there are a few fields that are present in the extensions object. Each field is described in the table below. In the next sections, we'll see how to take these parameters and use them to complete reauthorization.

Reauthorization Extension Parameters
codeConstant value "REAUTHORIZATION_REQUIRED"Error Code
userInteractionUrlA url that you'll need to redirect your users to so that they can complete reauthorizationUrl
reauthorizationTypeCurrently will only be the value "login"String
idA unique identifier that can be used to query the results of the reauthorization requestID

Building the reauthorization URL

To complete reauthorization, you'll need to direct your user to the userInteractionUrl with one of your whitelisted reauthorization redirect URIs added as a query string parameter with the key redirect_uri.

The URL must be URL encoded, and for security purposes must exactly match the value provided to Stitch (see footnote 1).

For the Stitch IDE clients, the currently configured redirect URI is, and thus the full URL you'd present to users if you encountered the example error above would be:


Handling the reauthorization callback

Once the user completes or cancels reauthorization, they'll be redirected back to the redirect_uri. The redirect uri will include three query string parameters.

Reauthorization Callback Query Parameters
idThe unique id of this reauthorization requestID
subThe OpenID subject or user idID
statusStatus will have the value "complete" if successful, or "failed" if not.String

Querying the results of reauthorization

You can also use the id from the original GraphQL error response to poll the reauthorization status. This can be done using the node query:

Simulating reauthorization with Test Users

Test users for Standard Bank and Capitec support simulating the reauthorization process.

Triggering reauthorization for these users can be done using via the API using the mutation below. Just make sure that to select the appropriate test user.

The next API call made will fail with a reauthorization error. You can complete the reauthorization using the OTP returned by the mutation. This OTP will also be present in the SSO UI.

  1. Please consult the prerequisites section in Stitch SSO for information about configuring the different redirect URIs for your client