Skip to main content
POST
/
v2
/
link
/
token
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>' \
     --data '
{
     "user_id": "1875c190-0cd6-46c1-8670-5b56a7794b78"
}
'

{
  "link_token": "dGVzdCB0ZXN0IHRlc3Q=",
  "link_web_url": "https://link.tryvital.io/?token=dGVzdCB0ZXN0IHRlc3Q%3D&env=production&region=us"
}
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>' \
     --data '
{
     "user_id": "1875c190-0cd6-46c1-8670-5b56a7794b78"
}
'

Authorizations

​
x-vital-api-key
string
header
required

Vital Team API Key

Body

application/json
​
user_id
string<uuid>
required

User id returned by vital create user request. This id should be stored in your database against the user and used for all interactions with the vital api.

​
provider
enum<string> | null

ℹ️ This enum is non-exhaustive.

Available options:
oura,
fitbit,
garmin,
whoop,
strava,
renpho,
peloton,
wahoo,
zwift,
freestyle_libre,
abbott_libreview,
freestyle_libre_ble,
eight_sleep,
withings,
apple_health_kit,
manual,
ihealth,
google_fit,
beurer_api,
beurer_ble,
omron,
omron_ble,
onetouch_ble,
accuchek_ble,
contour_ble,
dexcom,
dexcom_v3,
hammerhead,
my_fitness_pal,
health_connect,
polar,
cronometer,
kardia,
whoop_v2,
ultrahuman,
my_fitness_pal_v2,
map_my_fitness,
runkeeper
​
redirect_url
string | null
​
filter_on_providers
enum<string>[] | null

An allowlist of providers dictating what Vital Link Widget should show to the end user. If unspecified, all linkable providers are shown.

This has no effect on programmatic Vital Link API usage.

Minimum length: 1
​
on_error
string | null

By default, Vital Link Widget input forms for password and email providers have in-built error handling.

Specifying on_error=redirect disables this Vital Link Widget UI behaviour — it would instead redirect to your redirect_url, with Link Error parameters injected.

This has no effect on OAuth providers — they always redirect to your redirect_url. This also has no effect on programmatic Vital Link API usage.

Allowed value: "redirect"
​
on_close
string | null

By default, Vital Link Widget closes the window or tab when the user taps the Close button.

Specifying on_close=redirect would change the Close button behaviour to redirect to your redirect_url with the user_cancelled error specified.

This has no effect on programmatic Vital Link API usage.

Allowed value: "redirect"

Response

Successful Response

​
link_token
string
required

A short-lived Vital Link token for your Custom Link Widget to communicate with the Vital API.

​
link_web_url
string
required

The web browser link to launch the default Vital Link experience. If you requested the token for one specific provider, the link would redirect directly to the provider authentication flow. Otherwise, the user would be presented with a list of providers based on your team and token configurations.