Authenticate users through your own web app

You can use your own web app for the SMB user connection journey for Sage Bank Feeds

Our Sage Bank Feeds integration uses an authorization UI to authenticate an SMB user based on their submitted data connection ID. Your SMB users are represented in Codat as Companies. To learn how this method works, see SMB user flow: Connect a source bank account to Sage.

Instead of this UI, your own web app can authenticate SMB users based on the Company and data connection they're linked to. With this method, when a user selects your organization as a bank feeds provider in a Sage product, they're redirected to your web app instead of the Codat authorization UI.

Prerequisites

You must have completed the following setup tasks:

• Enable the Sage Bank Feeds integration
• Create a company to represent the SMB user
• Create a data connection for the company to the Sage Bank Feeds integration
• Add one or more source bank accounts to make available to the SMB user

For help with completing these tasks, see Enable the Sage Bank Feeds integration and Create a Company and data connection, then add bank accounts.

Configure your custom web app as a redirect URL

First, configure the Sage Bank Feeds integration to use your web app's URL as the authorization redirect URL.

1. In the Codat Portal, go to the Bank feed integrations page.

2. Click Manage next to Sage Bank Feeds.

3. Enter the URL of your custom web app as the Authorization redirect URL. For example:

   

4. Click Save.

Understand authentication flows

There are two authentication flows between Sage, Codat's Sage Bank Feeds integration, and your web app.

Sage redirects the user to your web app

1. In Sage, the SMB user selects the Banking tab.

2. They click the Connect Bank button.

3. They search for and select your organization from among the list of bank feed providers.

4. They select a target bank account—the account that will receive bank feeds from your application.

5. The user is redirected from Sage to a URL which is constructed as follows:

   https://{authorizationRedirectUrl}?authorizationId={authId}&redirectUri={redirectUri}&bankId={bankId}
   1. The authorizationRedirectUrl is the web app URL that you configured in the Codat Portal.
   2. The authId is the unique authorization identifier for the company.
   3. The redirectUri is the URI the SMB user will be redirected to after authentication through your web app (see step two in the next procedure).
   4. The bankId is a unique Id that represents the bank the SMB has attempted to link to in Sage (this will be a bank representing your organisation).

6. As configured in your web app, the user is redirected to a login or user authorization page.

7. The SMB user logs in to your web app.

8. Your web app authenticates the user against the Codat company and data connection to which they are linked.

Iframe

Sage will display your pages within an iframe embedded in the Sage product. Ensure that your UI can be used within this format.

You must include the "Content-Security-Policy" header with a value of frame-ancestors 'self' https://*.sagebankdrive.com https://*.sage.com https://*.intacct.com https://*.sageone.com to ensure it functions within the iframe.

Your web app redirects the user to the bank account selection screen

1. After a prompt, your web app sends a request to the PUT /authorization endpoint. The authId and 'bankId' (both from the URL in step five of the previous procedure) must be supplied in the request body as additional properties:

   PUT company/{companyId}/connections/{connectionId}/authorization

   Request body:

   {
      "authorizationId": {authId}
   }

2. If the PUT /authorization request returns a 200 response, your web app should redirect the SMB user to the redirectUri for the Company, with the authId appended as a query parameter:

   {redirectUri}?state={authId}
   
   // example:
   
   redirect_uri=https://snd01eu.sagebankdrive.com/api/v1/indirectredirect/11111-22222-33333-88888-9999?state=1122-3344-5566-7788

3. If the SMB user was successfully authenticated with Codat, Sage displays a dialog listing the available source bank accounts—the bank account in your application that will send bank feeds. For example:

   

4. The SMB user selects the bank account they want to use, then clicks OK.

5. Sage redirects the SMB user to the Sage product from which they began the authentication flow.

You can now use the GET /bankFeedAccounts endpoint to retrieve the source bank accounts and write bank transactions. For details, see Use your Sage Bank Feeds integration.