Integrating the Link SDK - Data API

The Fiskil Link SDK makes it simple to launch the consent flow inside your web application. You provide an auth_session_id created on your backend, and the SDK handles the rest — from rendering the consent UI to returning the result of the flow.

To use this SDK, you'll need a Fiskil team account. If you don't have an account, you can get in touch for a quick demo. If you're new to the Fiskil platform, start with the Quick Start Guide.

Integration Flow

1) Install Link SDK

This step is only required if you're using Node.js — for browser usage, you can import the SDK directly from CDN.

npm install @fiskil/link
# or
pnpm add @fiskil/link

2) Create an Auth Session

On your backend, call the /v1/auth/session endpoint with the end user ID. Unlike redirect flow, you don't need to specify redirect_uri and cancel_uri — only end_user_id is required.

curl --request POST \
  --url https://api.fiskil.com/v1/auth/session \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \
  --data '{"end_user_id": "${end_user_id}"}'

3) Launch the SDK

In your frontend, call the link() function with the auth_session_id to open the consent flow. On success, the result contains a consentID which can be used to fetch user data from the Fiskil APIs, or an error code on error.

4) Handle the Result

When the flow finishes, the SDK resolves with { consentID?, redirectURL? }. If the flow fails or the user exits, it rejects with a typed error.

Quick Start (ESM / TypeScript)

import { link } from '@fiskil/link';

// Start the consent flow
const flow = link('auth_session_id');

try {
  const result = await flow;
  console.log('Consent ID:', result.consentID);
  // Use consentID to fetch data via Fiskil APIs
} catch (err) {
  console.log('Link error code:', (err as any).code);
}

// To cancel the flow programmatically
// flow.close();

Quick Start (UMD / CDN)

<!-- Include the SDK from the Fiskil CDN -->
<script src="https://cdn.jsdelivr.net/npm/@fiskil/link@0.1.6-beta/dist/fiskil-link.umd.js"></script>
<script>
  // Launch the consent flow with your auth_session_id
  const flow = FiskilLink.link('auth_session_id');

  // Handle the result
  flow
    .then((result) => {
      console.log('Consent complete:', result.consentID);
      // Use consentID to fetch data from Fiskil APIs
    })
    .catch((err) => {
      console.error('Consent failed:', err);
    });

  // You can also close the flow programmatically if needed:
  // flow.close();
</script>

API Usage

`link(sessionId, options?)`

Creates and mounts the consent UI. Returns a LinkFlow object that is both:

a Promise that resolves to either LinkResult or LinkError based on the flow result, and
a controller with .close() to cancel the flow programmatically

Options

Option	Type	Description
`allowedOrigin`	`string`	Restrict postMessage origin (recommended in production).
`timeoutMs`	`number`	Rejects if no message is received within this time. Default: `600000` (10 min).

Result

When the consent flow is completed successfully, the link flow resolves with the LinkResult payload, which includes the consentID to fetch user data from the Fiskil platform.

type LinkResult = {
  consentID?: string;
};

consentID — use this to retrieve data from Fiskil APIs

Error Handling

The promise rejects with a LinkError if any error is encountered during the consent flow. For LINK_INVALID_SESSION, the iframe remains mounted. You can close it programmatically with .close().

interface LinkError extends Error {
  name: 'LinkError';
  code: LinkErrorCode;
  details?: unknown;
}

Error Codes

Code	Description
`LINK_NOT_FOUND`	Consent UI container not found in DOM
`LINK_TIMEOUT`	Flow exceeded timeout duration
`LINK_USER_CANCELLED`	User cancelled or flow closed programmatically
`LINK_INVALID_SESSION`	The provided Auth Session is invalid
`LINK_ORIGIN_MISMATCH`	Message received from unexpected origin
`LINK_INTERNAL_ERROR`	An unrecognized internal error occurred
`CONSENT_UPSTREAM_PROCESSING_ERROR`	Institution-level error during consent
`CONSENT_ENDUSER_DENIED`	User denied consent
`CONSENT_OTP_FAILURE`	OTP verification failed
`CONSENT_ENDUSER_INELIGIBLE`	User not eligible for data sharing
`CONSENT_TIMEOUT`	User abandoned the flow before completing it

For troubleshooting guidance, see Error Types.

React Integration Example

import { useState } from 'react';
import { link } from '@fiskil/link';

function LinkAccountButton({ authSessionId, onSuccess }) {
  const [loading, setLoading] = useState(false);

  const handleClick = async () => {
    setLoading(true);
    try {
      const result = await link(authSessionId);
      onSuccess(result.consentID);
    } catch (err) {
      console.error('Link failed:', err.code);
    } finally {
      setLoading(false);
    }
  };

  return (
    <button onClick={handleClick} disabled={loading}>
      {loading ? 'Connecting…' : 'Link Account'}
    </button>
  );
}

Next Steps

Review the Flow Overview to understand the user experience.
Set up Webhooks to listen for consent events.
Begin retrieving data through the Banking API or Energy API.