Launching Link

Junction Link API covers only cloud-based providers.Your mobile app has to manage connections with SDK-based providers — such as Apple HealthKit and Android Health Connect — through the Junction Mobile Health SDK, separately from Junction Link.

Your Backend

Create a Junction Link Token for a user using the Create Link Token endpoint.

A Junction Link Token expires 60 minutes after its creation.

import { JunctionClient, JunctionEnvironment } from "@junction-api/sdk";

const client = new JunctionClient({
    apiKey: "YOUR_API_KEY",
    environment: JunctionEnvironment.Sandbox,
});

const data = await client.link.token({
    userId: "<user_id>",
    provider: "oura",
});

from junction import Junction, Providers
from junction.environment import JunctionEnvironment

client = Junction(
    api_key="YOUR_API_KEY",
    environment=JunctionEnvironment.SANDBOX,
)

data = client.link.token(user_id="<user_id>", provider=Providers.OURA)

import com.junction.api.Junction;
import com.junction.api.core.Environment;
import com.junction.api.resources.link.requests.LinkTokenExchange;
import com.junction.api.types.Providers;

Junction client = Junction.builder()
    .apiKey("YOUR_API_KEY")
    .environment(Environment.SANDBOX)
    .build();

var data = client.link().token(
    LinkTokenExchange.builder()
        .userId("<user_id>")
        .provider(Providers.OURA)
        .build()
);

import (
    "context"

    junction "github.com/junction-api/junction-go"
    "github.com/junction-api/junction-go/client"
    "github.com/junction-api/junction-go/option"
)

c := client.NewClient(
    option.WithApiKey("YOUR_API_KEY"),
    option.WithBaseURL(junction.Environments.Sandbox),
)

provider := junction.ProvidersOura
response, err := c.Link.Token(context.TODO(), &junction.LinkTokenExchange{
    UserId:   "<user_id>",
    Provider: &provider,
})
if err != nil {
    return err
}
fmt.Printf("Received data %s\n", response)

curl --request POST \
     --url {{BASE_URL}}/v2/link/token \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'x-vital-api-key: <API-KEY>'

Your Frontend

Use the Link Token to launch the Link Widget on your frontend.

Option 1: Opening the Link Widget by URL

You can launch the Junction Link Widget using the Link Web URL (link_web_url) as provided by the Generate a Link Token endpoint:

If you have created the Link Token for a specific OAuth provider, Junction Link will dispatch the user automatically to the provider’s sign-in page.
Otherwise, your user will be presented with a list of providers to connect to. You can customize the list via the filter_on_providers parameter when creating the Link Token.

When the Link flow completes, the flow will redirect to the redirect_url you specified earlier when creating the Link Token. We will also append query parameters to the redirection target based on the Link flow outcome:

Flow state	Query parameters
Success	`state=success`
Error	See Link Errors.

Option 2: Using the `useVitalLink` React hook (`@tryvital/vital-link`)

Launching Junction-Link

import 'react-app-polyfill/ie11';
import * as React from 'react';
import * as ReactDOM from 'react-dom';
import { useCallback } from 'react';

import { useVitalLink } from '@tryvital/vital-link';
import { useState } from 'react';

const API_URL = process.env.API_URL ? process.env.API_URL : "http://localhost:3001"

const getTokenFromBackend = async (userKey: string, env: string) => {
  const resp = await fetch(<backend_url>);
  return await resp.json();
};

const App = props => {
  const userKey = '560596b9-924b-4af9-a670-cf21870fdac5';
  const [isLoading, setLoading] = useState(false);

  const onSuccess = useCallback(metadata => {
    // Device is now connected.
  }, []);

  const onExit = useCallback(metadata => {
    // User has quit the link flow.
  }, []);

  const onError = useCallback(metadata => {
    // Error encountered in connecting device.
  }, []);

  const config = {
    onSuccess,
    onExit,
    onError,
    env: "sandbox"
  };

  const { open, ready, error } = useVitalLink(config);

  const handleVitalOpen = async () => {
    setLoading(true);
    const token = await getTokenFromBackend(userKey, "sandbox");
    open(token);
    setLoading(false);
  };

  return (
    <button
      type="button"
      className="button"
      onClick={handleVitalOpen}
      disabled={isLoading || !ready}
    >
      Open Junction Link
    </button>
  );
};

ReactDOM.render(<App />, document.getElementById('root'));

Bring Your Own OAuth

Junction iOS App

Providers

Connecting Providers

Device Data

Mobile SDKs

Provider Guides