Skip to main content
The Auth SDK is a Deck authored client-side component that your users interact with to link their external accounts to your product and allow access to their data via the Deck API. It provides a secure interface that handles authentication and multi-factor authentication challenges.
Auth SDK - View 1Auth SDK - View 2Auth SDK - View 3
User-facing consent paneCredential submission interfaceSuccess screen

​
Prerequisites

​
Flow Diagram

Auth SDK flow diagram

​
Integration Guide

1

Install the SDK

Add the Auth SDK script to your application. Supported platforms include React, Next.js, Expo, Vue, Angular, TanStack, and vanilla JavaScript.
<script src="https://link.deck.co/link-initialize.js"></script>
For React/Next.js: Dynamically load the script in a useEffect:
useEffect(() => {
  const script = document.createElement('script');
  script.src = 'https://link.deck.co/link-initialize.js';
  script.async = true;
  document.body.appendChild(script);

  return () => {
    document.body.removeChild(script);
  };
}, []);
See complete examples in our SDK Quickstart repository.
2

Set up environment variables

Configure your Deck API credentials as environment variables. These are required to generate SDK tokens and must never be exposed in frontend code. Both keys are available in your Dashboard..env
DECK_CLIENT_ID=your_client_id_here
DECK_CLIENT_SECRET=your_secret_here
3

Generate a SDK Token

Create a server-side API endpoint to generate SDK tokens. Specify which data sources to make available using source_ids.The source_ids parameter controls which data sources appear in the Auth SDK for your users to select. You can specify one or multiple sources. Find source GUIDs in your Dashboard or the Sources guide.
Link tokens expire after 20 minutes and are one-time use.
curl -X POST https://sandbox.deck.co/api/v1/link/token/create \
  -H "Content-Type: application/json" \
  --header 'x-deck-client-id: <api-key>' \
  --header 'x-deck-secret: <api-key>' \
  -d '{
    "source_ids": ["b1af8246-0339-4833-9119-11da6bd68c13"]
  }'
Response:
{
  "link_token": "link-sandbox-abc123..."
}
4

Initialize the SDK

Add a button to your page that will launch the Auth SDK:
<button id="connect-btn">Connect Your Account</button>
Then fetch a SDK token from your backend and initialize the SDK:
// Fetch link token from your backend
const response = await fetch('/api/create_link_token', {
  method: 'POST',
});
const { link_token } = await response.json();

// Initialize Auth SDK
const deck = Deck.create({
  token: link_token,
  onSuccess({ job_guid }) {
    // Send job_guid to your backend to match with webhook
    fetch('/api/save_connection', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ job_guid })
    });
  },
  onError({ reason }) {
    if (reason === 'InvalidCredentials') {
      alert('Invalid credentials. Please try again.');
    }
  },
  onExit() {
    console.log('User closed Auth SDK');
  },
});

// Open Auth SDK when user clicks "Connect"
document.getElementById('connect-btn').addEventListener('click', () => {
  deck.open();
});
5

User Connects Their Account

When the user opens Auth SDK, they will:
  1. Consent to connect their credentials via Deck to your product.
  2. Select their data source from the options you chose to present them when creating the token
  3. Enter their credentials. During sandbox testing you can enter random strings.
  4. Complete any MFA challenges
The SDK handles all of this automatically. Your onSuccess callback receives the job_guid, and your webhook receives both the access_token and job_guid.
6

Receive access tokens via webhook

Create a webhook endpoint to receive access tokens after successful authentication. Configure the webhook URL in your Dashboard.Expected Webhook Payload:
{
  "job_guid": "b3ab44de-f722-4685-ab3a-b27b369e859b",
  "output": {
    "access_token": "access-sandbox-34343434-bcbc-34bc-34bc-343434343434"
  },
  "webhook_type": "Job",
  "webhook_code": "EnsureConnection",
  "environment": "Sandbox"
}
7

Use Access Tokens to Run Jobs

Once you receive the access_token via webhook, use it to run jobs on behalf of the user. Jobs can read data (e.g., fetch documents, invoices) or write data (e.g., submit orders, update records).See the jobs guide for more information on available jobs and how to run them.

​
Customization Options

You can customize the Auth SDK’s appearance and behavior by passing additional parameters when creating the link token in Step 2. See the complete API reference for all available options. A limited set of Auth SDK customizations can also be performed in the Dashboard.
Set the SDK’s display language:
{
  "language": "EN"
}
Supported languages: EN (English), ES (Spanish), FR (French), PT (Portuguese), DE (German)
Limit sources by their type (e.g., utility, telecom, logistics):
{
  "source_types": ["utility", "telecom"]
}
Launch the SDK in update mode to refresh an existing connection:
{
  "update": {
    "access_token": "access-sandbox-34343434-bcbc-34bc-34bc-343434343434",
    "mode": "UpdateCredentials"
  }
}
Use this when a user needs to update their credentials or re-authenticate due to password changes.
Override the default webhook URL for this session:
{
  "webhook_url": "https://yourdomain.com/custom-webhook"
}

​
Browser Support

Deck officially supports the Auth SDK on the following browsers:
DesktopMobile
Chrome 109+Android Chrome 121+
Safari 15.6+iOS Safari 15.6+
Firefox 115+
Edge 120+
Opera 105+

​
SDK Reference

​
Initialization Parameters

​
token
string
required
The token is required to launch the Auth modal. Tokens expire after 20 minutes and are one-time use.
​
onSuccess
function
required
Callback function called when a connection is successfully created.Receives: { job_guid: string }
onSuccess({ job_guid }) {
  // Send job_guid to your backend
  fetch('/api/save_connection', {
    method: 'POST',
    body: JSON.stringify({ job_guid })
  });
}
​
onError
function
Callback function triggered when the SDK encounters an error.Receives: { reason: string }Common error reasons:
  • InvalidCredentials - Username or password is incorrect
onError({ reason }) {
  if (reason === 'InvalidCredentials') {
    showError('Invalid credentials. Please try again.');
  }
}
​
onExit
function
Callback function triggered when a user closes or exits the SDK without completing the flow.
onExit() {
  console.log('User closed Auth SDK');
}

​
SDK Functions

Displays the Auth SDK and starts the authentication flow.
const deck = Deck.create({ token, onSuccess, onError, onExit });
deck.open();
Call this method when the user clicks your “Connect Account” button.
Closes the Auth SDK programmatically and triggers the onExit() callback.
deck.exit();
Use this to close the SDK from your code (e.g., after a timeout or user action).
⌘I