This is a staging build of the docs
We've reorganized our products to make building with Codat easier than ever
Skip to main content

Build your own auth flow

Codat provides a series of endpoints that allow you to build the journey for your business customers to connect their financial platforms.

Codat provides a series of endpoints that allow you to build the journey for your business customers to connect their financial platforms.

What might a bespoke auth flow look like?​

Below is a indicative demo of a where Codat might fit in to a digital lending onboarding experience. Copay is a fictional digital lender looking to gather financial data from prospective customers in order to make a credit decision.

See an indicative demo | See the code

Building your own auth flow​

1. Create a Codat company when a user signs up for your app​

  1. In order to establish a connection to your customer's financial platform(s), you first need to create a Codat company for them. We recommend you create a company at the same time as your customer signs up within your app. That will allow you to track their connection status from day one. To create a company, follow the steps in Create a Codat company.
Use your merchant ID for the company name

We recommend that you populate the name value with the ID that you use for the merchant in your internal system so that it’s easier to identify the Codat company that corresponds to your record of the merchant.

  1. From the response to step 1, retain the company ID (hereafter referred to as companyId) (see an example below). It is crucial that you retain this value as you will need it for directing your customers to Link and managing their connections.
  2. (Optional) Set up a webhook to monitor the connection status of the newly created company.

  1. Retrieve a list of all integrations available to connect and display them in your UI:

    GET /integrations",

    Use a query filter in the following format:

    ?query=sourceType=accounting&&enabled=true

    In the query above, the enabled parameter allows you to filter the integrations based on whether or not they have been enabled via the Codat portal. The sourceType parameter allows you to filter the integrations by the data type: accounting, banking or commerce.

    Note that you need to URL encode the query:

          "code": "//Non-encoded query:
          ?query=sourceType=accounting&&enabled=true

          //Encoded query:
          ?query=sourceType%3DAccounting%26%26enabled%3Dtrue",

More information about querying can be found in Querying. If you are using the API reference, you don't need to encode the query, it happens automatically.

  1. Retrieve branded assets, including logos and buttons, for the selected integrations:
GET /integrations/{platformKey}/branding",
Cache branding assets

To ensure this page is performative for your users, we recommend caching the branding assets information rather than calling the branding endpoint each time a user visits the integration selection page.

Use the branded assets provided by Codat

We recommend using the assets provided by Codat as they meet the requirements of the supported integrations. For example, Intuit integrations (QuickBooks Online and QuickBooks Desktop) require the specific use of QuickBooks branded buttons, including specific hover states.

3. Direct your user to enter their 3rd party credentials to authorize a connection with their selected platform​

  1. Create a data connection for the integration selected by your customer:

POST /companies/{companyId}/connections

Request body:

"platformKey"",

The platformKey is the unique key Codat uses instead of financial platform names to remove the dependence on a platform's display name. View the list of our accounting, commerce, and banking platform keys, or retrieve them using our API.

  1. Direct your user to the linkUrl found in the nested dataConnection object for the specified integration, returned in the response. It will prompt the user to enter their credentials for the 3rd-party platform, authorizing the connection and activating it.
Platform-specific pages

For some integrations, the authorization flow will include additional setup instructions or steps. For example:

  • Sage Intacct and NetSuite require complex user permissions
  • Microsoft Dynamics 365 Business Central requires your users to install a package on their machine
  • Xero requires the company to confirm their name before redirecting to Xero to connect
  1. Once the user has successfully authenticated in their platform and thus authorized a data connection, redirect them back to your app. Ensure you handle all possible redirect status codes and error messages so that your users understand when something has gone wrong. Read Redirect URLs to learn more about how redirect URLs are used with Codat's products.

If you don't set a redirect URL, the user will be presented with a pre-built success page.

If a redirect URL is not set, then pre-built UI will be presented to your user. This will be the success and overview page of Link - our pre-built white-labelled UI.

Rules on number of connections to different integration types

A company may link a single source of accounting data but multiple sources of banking or commerce data. Any combination of accounting, banking, and commerce connections is allowed. For more on data connections and connection statuses see Data connections.

4. Confirm successful authorization and data synchronization​

  1. Once the connection is complete (for guidance on how to monitor the connection, read Set up webhooks), mark the connection as authorized and confirm to your user the successful authorization of the connection.
  2. Monitor the synchronization of data (also available in our API):
GET https://api.codat.io/companies/{companyId}/dataStatus",

Once the initial synchronization of data is complete, you can inform the user accordingly and continue the flow of your app.

5. Allow your users to manage their ongoing connection(s)​

Have the following values at hand:

  • The company id of the Codat company that represents the user, hereafter referred to as companyId
  • The id of the connection you want to modify, hereafter referred to as connectionId

To get these values:

GET /companies

//Example response:
{
        //Company ID
        "id": "40ef18ac-acf0-4ea1-8667-05398c0b75fa",
      //End of company ID
      "name": "Superapp",
      "platform": "",
      "redirect": "https://link.codat.io/company/40ef18ac-acf0-4ea1-8667-05398c0b75fa",
      "dataConnections": [],
      "created": "2022-05-16T15:51:03Z"
    },
    {
      //Platform connection ID
      "id": "1126743b-113d-4d72-b14f-36d6742df487",
      //End of platform connection ID
      "name": "Superapp",
      "platform": "Xero",
      "redirect": "https://link.codat.io/company/1126743b-113d-4d72-b14f-36d6742df487",
      "lastSync": "2022-05-16T15:52:15.6455941Z",
      "dataConnections": [
        {
          "id": "f42c2cbe-dfab-4b13-a16f-51729c75bd2e",
          "integrationId": "0f20c943-12d0-4800-9f6c-d218f62d494c",
          "sourceId": "8a156a5a-39cb-4f9d-856e-76ef9b9a9607",
          "platformName": "Xero",
          "linkUrl": "https://link-api.codat.io/companies/1126743b-113d-4d72-b14f-36d6742df487/connections/f42c2cbe-dfab-4b13-a16f-51729c75bd2e/start",
          "status": "Linked",
          "lastSync": "2022-05-16T15:52:15.6455938Z",
          "created": "2022-05-16T15:00:00Z",
          "sourceType": "Accounting"
        }
      ],
      "created": "2022-05-16T14:55:22Z"
    },

Allow users to view existing connections for their company​


GET /companies/{companyId}/connections",

This endpoint is also available in Common API.

In the request above, the companyId is the companyId that was returned to you when you created a Codat company for the user. It can also be found in the company's metadata.

Allow users to revoke access to their platform​

Allow your users to prevent further synchronizations with a connection, whilst still allowing you to access data that has already been pulled or pushed:

POST /companies/{companyId}/connections

Request body:

"platformKey"

This endpoint is also available in Common API.

Allow users to delete a connection​

To delete a connection entirely, preventing both further synchronizations and the ability to make any data pulls or pushes:

DELETE /companies/{companyId}/connections/{connectionId}",

Bonus: Show that your authorization flow is powered by Codat​

To boost your customers' trust, you can embed our "Powered by Codat logo" into your application.

You can download the logo or link it from our content delivery network:

Powered by Codat
Was this page useful?
❤️
👍
🤔
👎
😭

Contents

Suggest edits