Setup

The Cobalt Link flow has the following steps:

Call https://api.usecobalt.com/link/token/create to create a link_token and pass it to your app’s client.
Use the link_token to open Link for your user. In the onSuccess callback, Link will provide a temporary public_token.
Call https://api.usecobalt.com/link/token/exchange to exchange the public_token for a permanent access_token.
Store the access_token and use it to make API requests.

Detailed Steps

Create Link Token

The /link/token/create endpoint creates a link_token, which is required as a parameter when initializing Link. Once Link has been initialized, it returns a public_token, which can then be exchanged for an access_token via /link/token/exchange as part of the main Link flow.

curl -X POST https://api.usecobalt.com/link/token/create \
-H 'Content-Type: application/json' \
-H 'client_id: "%COBALT_CLIENT_ID%"' \
-H 'client_secret: "%COBALT_CLIENT_SECRET%"' \
-d '{
  "user_id": "%REFERENCE_USER_ID%",
  "org_id": "%REFERENCE_ORG_ID%"
}'

The request requires the following parameters:

client_id this is your Cobalt API client id.
client_secret this is your Cobalt API secret.
user_id this is a unique ID representing the end user. Typically this will be a user ID number from your application. Personally identifiable information, such as an email address or phone number, should not be used in the user_id.
org_id this is the ID of the organization that this user belongs to in your system. This is often a clinic or hospital. This association is important to handle any custom settings that an org has.

Example response:

{
    "success": true,
    "token": "189hisdf78w9r3ysdfhi" // used in next step.
}

Initialize Client Link

Lightbox Mode

Lightbox Mode will activate the Cobalt Link experience in a modal rather than having the element appear directly embedded elsewhere on the page. The lightbox takes up the entire user’s screen, darkening the background content with a semi-transparent overlay of the page and centering Cobalt’s Link UI in a modal located at the center of the user’s screen.

To utilize Lightbox mode, include the Javascript snippet on your site, before the closing </body> tag. Make sure to attach a button’s onClick event to call the launch_cobalt() function. Alternatively, you can call the window.CobaltLink.init() function directly within an event callback of your choice.

CobaltLink.init accepts one argument, a configuration Object. The configuration object requires the following parameters:

token this is the temporary link_token from the create link token step.
onSuccess this callback is called when a user successfully links their account. It takes one arguments: the public_token. The public_token can then be used in the exchange public token step.

New Window Mode

If you prefer to not include the Cobalt Link code in your site you can direct the user to complete the Link flow in a separate window. Do this by sending the user to https://link.usecobalt.com?token={link_token}. Once the user completes the flow they will be redirected back to your callback_url along with the public_token (eg. https://{YOUR_CALLBACK_URL}?token={public_token}). You can then use the public_token in the next step. If you haven’t set up a callback_url yet it will default to google.com and you’ll see the token in the browser’s address bar after the redirect.

Exchange Public Token

The /link/token/exchange endpoint exchanges a public_token for an access_token.

curl -X GET "https://api.usecobalt.com/link/token/exchange" \
-H 'Content-Type: application/json' \
-H 'client_id: "%COBALT_CLIENT_ID%"' \
-H 'client_secret: "%COBALT_CLIENT_SECRET%"' 
-G \
--data-urlencode "public_token=234p852489035y29083y4" \

The request requires the following parameters:

client_id this is your Cobalt API client id.
client_secret this is your Cobalt API secret.
public_token this is the token acquired during the Initialize Client Link step.

Example response:

{
    "success": true,
    "token": "9872394hjkldsfh987re9iwqhjosdffh9sdychosdofc"
}

Examples

Code snippet

<script async defer src="https://link.usecobalt.com/init.js"></script>

<script>
    function launch_cobalt() {
        window.CobaltLink.init({
            token: "%TEMPORARY_LINK_TOKEN%",
            onSuccess: (public_token) => {
              // send the public_token to your server so it can exchange it for an access_token
            },
        })
    }
</script>

Javascript

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Cobalt Demo</title>
    <link rel="stylesheet" href="index.css">
</head>
<body>
    <div id="button-container">
        <button id="loadAppButton">Link account</button>
    </div>

    <script src="https://link.usecobalt.com/init.js"></script>
    
    <script type="text/javascript">
        document.getElementById('loadAppButton').addEventListener('click', async function() {

            // Fetch the link token from the Cobalt API
            try {
                const publicTokenResponse = await fetch('https://api.usecobalt.com/link/token/create', {
                    method: 'POST',
                    headers: {
                        'Content-Type': 'application/json',
                        'client_id': '%COBALT_CLIENT_ID%',
                        'client_secret': '%COBALT_CLIENT_SECRET%'
                    },
                    body: JSON.stringify({ user_id: '%REFERENCE_USER_ID%', org_id: '%REFERENCE_ORG_ID%' })
                });
                const publicTokenData = await publicTokenResponse.json();
                
                if (publicTokenData && publicTokenData.token) {
                    // Initialize Cobalt Link with the fetched token
                    window.CobaltLink.init({
                        token: publicTokenData.token,
                        onSuccess: async (public_token) => {
                            console.log('got the public_token: ', public_token);
	                            
                            // Exchange the public token for the access token
                            const accessTokenResponse = await fetch(`https://api.usecobalt.com/link/token/exchange?public_token=${public_token}`, {
					                    method: 'GET',
					                    headers: {                        
						                    'Content-Type': 'application/json',
						                    'client_id': '%COBALT_CLIENT_ID%',
						                    'client_secret': '%COBALT_CLIENT_SECRET%'
						                  },
					                  });
						                const accessTokenData = await accessTokenResponse.json();
						                console.log('got the access_token: ', accessTokenData.token);
						                // Now you can save the access_token and use it to call the API
                    });
                } else {
                    console.error('Failed to obtain link token:', data.message);
                    messageEl.innerText = "Error: " + data.message;
                }
            } catch (err) {
                console.error('Failed to setup integration:', err);
                messageEl.innerText = "Error: " + err.message;
            }
        });
    </script>
</body>
</html>

React

import React, { useCallback, useState, useEffect } from "react";

// Custom hook from Cobalt for handling link operations.
// Run `npm i @cobalt-technology/react-link` to install the package. 
import { useCobaltLink } from "@cobalt-technology/react-link";

export default function CobaltLinkDemo() {
    const [linkToken, setLinkToken] = useState(null); // State to store the link token received from the Cobalt API
    const [publicToken, setPublicToken] = useState(""); // State to store the public token received from the onSuccess callback
    const [isReadyToInit, setIsReadyToInit] = useState(false); // State to determine if the component is ready to initialize the Cobalt link

    // Callback function to handle success after receiving public token
    const onSuccess = useCallback((public_token) => {
        console.log("got the public_token: ", public_token);
        setPublicToken("Public token: " + public_token);
        
        // Exchange the public token for the access token
        const accessTokenResponse = await fetch(`https://api.usecobalt.com/link/token/exchange?public_token=${public_token}`, {
	        method: 'GET',
	        headers: {                        
		        'Content-Type': 'application/json',
		        'client_id': '%COBALT_CLIENT_ID%',
		        'client_secret': '%COBALT_CLIENT_SECRET%'
		      },
				});
				const accessTokenData = await accessTokenResponse.json();
				console.log('got the access_token: ', accessTokenData.token);
				// Now you can save the access_token and use it to call the API
    }, []);

    // Destructuring the necessary methods and states from the useCobaltLink hook
    const { init, loading } = useCobaltLink({
        token: linkToken,
        onSuccess,
    });

    // Effect to initialize the Cobalt link once conditions are met
    useEffect(() => {
        if (isReadyToInit && linkToken && !publicToken) {
            init();
        }
    }, [isReadyToInit, linkToken, init]);

    // Function to request a link token from the Cobalt API
    const initLink = async () => {
        try {
            const response = await fetch(
                "https://api.usecobalt.com/link/token/create", {
                    method: "POST",
                    headers: {
                        "Content-Type": "application/json",
                        client_id: "%COBALT_CLIENT_ID%",
                        client_secret: "%COBALT_CLIENT_SECRET%",
                    },
                    body: JSON.stringify({ user_id: "%REFERENCE_USER_ID%", org_id: "%REFERENCE_ORG_ID%" }),
                }
            );
            const data = await response.json();
            if (data && data.token) {
                setLinkToken(data.token);
                setIsReadyToInit(true);
            } else {
                console.error("Failed to obtain link token:", data.message);
            }
        } catch (err) {
            console.error("Failed to setup integration:", err);
        }
    };

    // Render a button that triggers the initLink function
    return (
        <div>
            <button disabled={loading} onClick={initLink}>
                Link Account
            </button>
        </div>
    );
}

Introduction

Guides

Detailed Steps

Create Link Token

Initialize Client Link

Exchange Public Token

Examples

Code snippet

Javascript

React

Introduction

Guides

​Detailed Steps

​Create Link Token

​Initialize Client Link

​Exchange Public Token

​Examples

​Code snippet

​Javascript

​React

Detailed Steps

Create Link Token

Initialize Client Link

Exchange Public Token

Examples

Code snippet

Javascript

React