Skip to main content

Migration guide

Learn how to migrate from a custom link flow to our embedded Link component

Overview​

This guide helps you migrate from a custom link flow to our embedded Link component. Link offers a native, secure, and best in class experience to connect your customers’ financial software.

Prerequisites​

You need a JavaScript application to render the Link component. Our component works with vanilla JavaScript and all major JavaScript frameworks. TypeScript is supported and recommended.

Do not use Link inside an iframe. It won’t work due to CORS restrictions.

Your current implementation​

User experience​

Your current implementation likely starts with a consent page, confirming that your customers are happy to share their financial data with you before they interact with Codat. This often includes information on the purpose, platform data accessed, and your retention policy.

Codat's Link component optionally supports consent management and more, as part of your migration you may wish to leverage this native functionality to remove maintenance overhead in your application.

There are two common approaches for custom link flows, depending on your use case:

  • Create a company with a platformKey:
    You pass the company name and the financial software’s platformKey in one API call. Best suited for users connecting to a single financial system.

  • Create company and connection separately:
    You create the company first, then create a connection. This approach is typically followed when connecting several platforms for one customer e.g. Accounting Platform and Banking.

Custom Link workflow

The embedded Link component replaces your custom implementation while preserving the user experience elements you've already built. Instead of managing connection logic, API calls, and UI components in your frontend:

  1. Your backend requests an access token from Codat’s API.
  2. You pass the access token and company name to the Link component.
  3. The user completes the connection flow in the embedded UI.

Link supports both of your current approaches — whether you're using the platform key flow for single connections or the two-step approach for multiple software connections.

Embedded Link workflow

Retain your current user experience​

Your existing consent page, data sharing policies, and user onboarding flow don't need to change. Link is highly customizable, allowing you to:

  • Preserve your consent flow: Use custom consent pages with your existing messaging about data purpose and retention.
  • Maintain your branding: Control colors, logos, and styling to match your application.
  • Choose your layout: Display Link in modal or non-modal views based on your current UI patterns.
  • Control the journey: Decide when and how users interact with the connection flow.

This means you can migrate your implementation to leverage the features of our Link product, whilst maintaining your existing customer experience and consent journey.

Learn how to customize your auth flow

Migration steps​

Step 1: Set up CORS​

Cross-origin resource sharing (CORS) settings are required for access tokens to work. Configure CORS settings on your Codat instance:

  • Use Set CORS settings to register allowed domains
  • Use Get CORS settings to view your current configuration

Step 2: Implement access token retrieval​

  1. Create a backend endpoint to proxy Codat's API.
  2. In that endpoint, call GET /accessToken to retrieve an access token for the Link component.
  3. Return the accessToken in the response.
Install the npm package

Codat provides a types package on npm that contains type definitions for our Link component primitives. We recommend using this package as it simplifies your implementation.

npm install @codat/sdk-link-types

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 CodatLink.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.

  2. Use the component to mount the SDK

    We suggest wrapping the CodatLink component in a modal to adjust its positioning. Your component can also manage when to display the Link component, passing the relevant company ID and callbacks.

// AuthFlow.tsx

import {
  ConnectionCallbackArgs,
  ErrorCallbackArgs,
} from "@codat/sdk-link-types"
import { useState } from "react";
import { CodatLink } from "./components/CodatLink";

function App() {
  const [companyId, setCompanyId] = useState("");
  const [modalOpen, setModalOpen] = useState(false);
  const [isFinished, setIsFinished] = useState(false);

  const onConnection = (connection: ConnectionCallbackArgs) => {
    // Perform any logic here that should happen when a connection is linked
    console.log(`New connection linked with ID: ${connection.connectionId}`);
  }
  const onClose = () => setModalOpen(false);
  const onFinish = () => {
    onClose();
    setIsFinished(true);
  }
  const onError = (error: ErrorCallbackArgs) => {
    // this error should be logged in your error tracking service
    console.error(`Codat Link SDK error`, error);
    if (!error.userRecoverable) {
      onClose();
    }
  }

  return (
    <div>
      <p>Some content</p>

      <button onClick={() => setModalOpen(true)}>
           Start authing
      </button>

      {modalOpen && (
      <div className="modal-wrapper">
        <CodatLink
          companyId={companyId}
          onConnection={onConnection}
          onError={onError}
          onClose={onClose}
          onFinish={onFinish}
        />
      </div>
    )};
    </div>
  );
};

  1. Conditional steps

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

    • If you're using content security policy (CSP) headers, edit these headers:

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

Configure Link to match your current implementation:

Dynamic imports

Link SDK is imported at runtime, so you'll always get the latest version of our auth flow UI with no risk of staleness. To achieve this, we use ES6's import() feature (aka dynamic imports).

  • Remove your existing API calls:
  • Remove UI elements that Link now handles:
    • Custom integration selection interfaces.
    • Any consent pages now managed by Link.
Was this page useful?
👏
👍
🤔
👎
😭

Contents

Suggest edits