Skip to main content

Get started with Link SDK

Embed our auth flow in your application UI using our low-code component

Our Link SDK is a pre-built JavaScript component that neatly sits in your front-end code and can be deployed in a matter of minutes.

We built it to be flexible so that you can integrate and initialize it in any way you want, and provide the user with a native feel of your authorization journey. As a result, clients using the SDK note that 89% of their users successfully complete their journeys.

Live Editor
function AuthFlow() {
  const onConnection = (connection) => alert(`Connection: ${connection.connectionId}`);
  const onFinish = () => alert("On finish callback");

  const config = {
    companyId: "e0e0462f-d7f3-456f-b3e9-0b40afe0245e",
    options: {
      showLandingPage: true,
    }
  }

  return <div>
    <p>Click the button below to start authing.</p>

    <CodatLink {...config}/>
  </div>
}
Result
Loading...
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).

Resources​

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

Need help with designing your auth flow experience?

Our user experience team is ready to help you design a high converting and trusted auth flow, and ensure your user journey complies with integration partnerships' requirements. Speak to your account manager to set up time with our experts.

Indicative demo

Curious where Codat's Link flow might fit in your customer's experience? See our indicative demo.

Prerequisites​

Your application​

You need a JavaScript application to render the component in. The component works with all major JavaScript frameworks, including React, and with vanilla JavaScript. You can choose to implement it in TypeScript. We don't recommend using Link in an iframe because it will not work for security reasons (CORS).

The application should take care of creating companies programmatically and retrieving the companyId of any company you want to authorize. Additionally, build out the required redirect configuration within your application.

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, so our examples are prepared with that assumption.

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.

  1. 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";

export const AuthFlow = ({ companyId }: {companyId: Company["id"]}) => {
  const [modalOpen, setModalOpen] = useState(false);

  const onConnection = (connection: ConnectionCallbackArgs) => 
    alert(`On connection callback - ${connection.connectionId}`);
  const onClose = () => setModalOpen(false);
  const onFinish = () => alert("On finish callback");
  const onError = (error: ErrorCallbackArgs) => 
    alert(`On error callback - ${error.message}`);

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

Callback functions​

Callback functions allow you to build custom logic into our SDK.

We expose 4 props you can use to pass callback functions into the component.

  • onConnection - Called when a connection is successfully authorized and moved out of a pending state. Will execute with the connection as a parameter, which contains the connectionId
  • onFinish - Called when the user has completed all required steps and clicks 'Complete'.
  • onClose - Called when the user clicks the x button in the to right.
  • onError - Called when something goes wrong, returning the error.

You can configure Link's UI to match your company branding and reflect your company's values, and adjust Link's behavior using the Codat Portal or our SDK's advanced options.

Configure in Portal​

In the Codat Portal, navigate to Settings > Auth flow to view the auth flow settings pages. Use these to add UI copy, set file upload options, choose to make steps optional, or disable steps. We provide detailed instructions for each category of settings:

Configure in code​

If you need more control over the UI based on application-specific logic, want to vary it conditionally, or simply prefer to manage the UI in code, we offer programmatic control via the options property that overrides the Link settings set in the Portal. We explain these advanced options in detail:

To control the redirects that happen upon flow completion, you need to build out the required redirect configuration within your application.

Was this page useful?
👏
👍
🤔
👎
😭

Contents

Suggest edits