Skip to main content

Let clients manage their data with Connections SDK

Put your customers in control of their data connections with our pre-built embeddable component

Overview​

Give your customers the ability to manage the access permissions they have given you by using our Connections SDK in your front end. This is key from a regulatory perspective, builds trust between you and your customer, and is required by some accounting software (e.g. Xero).

An image of three in-app screenshots of the Connections UI. The first picture displays a list of three existing connections to Xero, Square, and Commerce Sandbox. The second image shows the entry for the Square connection with dates the authorization was given and recent data read dates. It also lists the option to disconnect the connection. The final image displays a confirmation of the disconnection.

Functionality​

With its sleek UI and low-code deployment, the component provides the following critical functionality:

  • Displays accounting, banking, and commerce connections in Linked, Unlinked, and Deauthorized statuses.
  • Provides the details of first authorization date and most recent sync date.
  • Allows the user to disconnect an active connection, setting it to a Unlinked state and retaining previously fetched data.
  • Enables the user to reauthorize a previously unlinked or deauthorized connection, setting it back to Linked status.
  • Provides additional controls over specific integrations (e.g. Pause the connector for QuickBooks Desktop).

You can read more about Connection statuses at Codat.

Example implementation​

We've provided rich examples on GitHub that illustrate how you can add the Connections component to your project.

Prerequisites​

Your application​

You need a JavaScript application to render the component. The component can be used in any part of your application and works with all major JavaScript frameworks, such as React and Typescript. You can also implement it in vanilla JavaScript. We don't recommend using it in an iframe because it will not work for security reasons (CORS).

Link SDK and Connections SDK

The Connections SDK is an independent component and doesn't require our Link SDK to work. You can use the Link SDK in your app to enhance your customers' auth flow experience and achieve an 89% average conversion rate.

Access token​

Once your customer authorizes within your application, use the Get access token endpoint to retrieve an access token for this customer's company.

Token validity

The token is only valid for one hour and applies to a single company.

const accessTokenRes = await platformClient.connectionManagement.getAccessToken({
    companyId: companyId,
  });

if(accessTokenRes.statusCode == 200){
  const accessToken = accessTokenRes.connectionManagementAccessToken.accessToken
  console.log(accessToken)
}

Pass the token to the Connections component so that we can get the company-specific information and display it in the UI. We summarized this process on the diagram:

CORS settings​

Cross-origin resource sharing (CORS) settings are required for the Connections component to work. To control the domain list that your application can make token requests from, register the allowed origins using the Set CORS settings endpoint.

To display the origins you previously registered for your instance, use the Get CORS settings endpoint.

Get started​

Install the npm package

Take advantage of our npm package so you don't have to manually import and maintain type definitions. You will benefit from it the most if you are using Typescript.

$ npm i -S @codat/sdk-connections

Get started with React​

For an example of the component in action, see our demo app.

  1. Create a component that mounts the SDK

You can copy and paste the example CodatConnections.tsx file to an appropriate location in your app. We recommend setting the component to width: 460px; height: 840px because it's optimized to look best with these parameters. The code snippet below uses these parameters.

  1. Use the component to mount the SDK

    We suggest wrapping the CodatConnections component in a modal so that you can adjust its positioning. It can also manage when to display the connections, passing the relevant access token and callbacks.

// ConnectionManagement.tsx

import {
  DisconnectCallbackArgs,
  ErrorCallbackArgs,
} from "@codat/sdk-connections";

import { CodatConnections } from "./components/CodatConnections";
import { useState } from "react";

export const ConnectionManagement = ({
  accessToken,
}: {
  accessToken: string;
}) => {
  const [modalOpen, setModalOpen] = useState(false);

  const onDisconnect = (connection: DisconnectCallbackArgs) =>
    alert(`On disconnect callback - ${connection.connectionId}`);
  const onReconnect = (connection: DisconnectCallbackArgs) =>
    alert(`On reconnect callback - ${connection.connectionId}`);
  const onClose = () => setModalOpen(false);
  const onError = (error: ErrorCallbackArgs) =>
    alert(`On error callback - ${error.message}`);

  return (
    <div>
      <p>Some content</p>
      <button onClick={() => setModalOpen(true)}>Manage connections</button>
      {modalOpen && (
        <div className="modal-wrapper">
          <CodatConnections
            accessToken={accessToken}
            onDisconnect={onDisconnect}
            onReconnect={onReconnect}
            onError={onError}
            onClose={onClose}
          />
        </div>
      )}
      ;
    </div>
  );
};

  1. If you're using content security policy (CSP) headers:

    • Allowlist Codat by adding *.codat.io to default-src (or each of of script-src, style-src, font-src, connect-src, img-src).
    • Add unsafe-inline to style-src. Don't use a hash because this can change at any time without warning.

  2. If you are using TypeScript, extend your type declarations with our types by installing the package using npm install --save-dev @codat/sdk-connections. Otherwise, delete the type-related code in the snippets.

Interface options​

The component doesn't support the branding and customization settings that you can apply to our Link auth journey in the Codat Portal. However, you can use the SDK's options property to change some of these settings.

<CodatConnections
  accessToken={accessToken}
 onClose: () => void = () => {};
 onError: ({correlationId?: string;
  message?: string;
  errorCode?: number;
  userRecoverable: boolean}) => void = () => {};
onReconnect: (args: {connectionId: string}) => void = () => {};
onDisconnect: (args: {connectionId: string}) => void = () => {};
  options={{
      text: {...},
  }}
/>

The options prop is optional and accepts an object containing the following optional properties:

PropertyDescription
textContains options that control what text is displayed to the user.

The object is applied as the SDK component is mounted and doesn't support reloading. Make sure to modify the options before mounting the component.

Custom text​

Use the text property to control some of the text displayed within the Connections UI. You can override the following text options:

OptionType and description
accounting.connectionDetails.dataTypes
banking.connectionDetails.dataTypes
commerce.connectionDetails.dataTypes		array[string] (accepts Markdown)

List of requested data types displayed before disconnecting or reconnecting an accounting, banking or commerce software.

If this is not set, the UI will not display a list of data types when disconnecting or reconnecting.

Changelog​

Change management

As with all Codat products, this SDK is subject to our change management policy. We will give appropriate notice for changes to it and any associated APIs. We have rigorous testing and security measures in place to ensure you can import our SDK with confidence.

April 2024​

  • Initial release of the SDK.
Was this page useful?
👏
👍
🤔
👎
😭

Contents

Suggest edits