Skip to main content

​
Vital Sign-In Token

In the Vital Sign-In Token scheme, each mobile app installation signs in with Vital Mobile SDK as an individual user in your Team. The app installation would be granted only Junction API access scoped to that specific user. Instead of hardcoding a Junction Team API Key, your app would request your own backend to generate a Vital Sign-In Token for the user, through your own API authentication and authorization systems. In this model, your Junction Team API Keys are kept strictly as a server-side secret.

Persistence

The signed-in user is persistent across app relaunch and device reboots.

Access Scope

Only user-level resources of the signed-in user can be accessed.

​
Overview

Sign in once

In typical circumstances, within each app installation, you would sign in your authenticated user only once with the Vital Mobile SDK. You would do so as part of your app’s user lifecycle.There are some known circumstances where you would have to sign in the user again:
  • You have signed out your user in response to your app’s user lifecycle changes; or
  • The Vital SDK sign-in state is out of sync with your app’s user lifecycle; or
  • The SDK automatically signed out, because it had detected the deletion of the Vital User.
It is unnecessary to request and sign-in with the Vital Sign-In Token every time your app launches.

Integrating into your app's user lifecycle

You should sign-in and sign-out of the Vital Mobile SDK as an integral part of your app’s user lifecycle:
  1. When the user signs in to your app, you would request the Vital Sign-In Token from your backend, and then sign in with the Vital Mobile SDK.
  2. When the user signs out from your app, you would also sign out from the Vital Mobile SDK.
Vital Mobile SDK persists the signed-in Vital User — as well as any settings and sync state — across app relaunches and device reboot.

A recommendation to perform regular reconciliation

We recommend regularly reconciling the state of the Vital Mobile SDK and your app’s user lifecycle. This is because:
  1. The SDK sign-in process involves remote API calls, which can fail due to Internet connectivity;
  2. Unknown edge cases in your integration of Vital Core SDK into your app’s user lifecycle may result in the state being out of sync; and
  3. If you are integrating Vital Mobile SDK into an existing production app, this reconciliation can serve as a one-off migration for app installations upgrading from an older version of your app.
You can achieve this through the Core SDK API in three steps:
  1. Query the Core SDK Status and the Current User ID;
  2. Compare these against your app’s user state; and
  3. Only if a discrepancy is detected, perform a Vital SDK sign-in or sign-out in accordance to the discrepancy.
You would typically schedule this as an asynchronous task that spawns when your application process launches.
Do not sign in and sign out every time your application process launches.

Technical details

Vital Sign-In Token is a short-lived bearer token issued for a specific Vital User. Vital Mobile SDK uses it to sign in with Vital’s Identity Provider as the Vital User represented by the token.Each app installation can only have one active signed-in Vital User.Internally, the Vital Mobile SDK:
  1. exchanges the short-lived Vital Sign-In Token for a permanent sign-in, which is in the form of an OAuth 2.0 access token and an OAuth 2.0 refresh token.
  2. discards the Vital Sign-In Token upon a successful exchange.
  3. stores these token secrets securely in the device persistent storage.
  4. calls the Junction API using the OAuth 2.0 access token.
  5. transparently manages the OAuth 2.0 refresh token flow to keep the access token fresh and valid.
This is why the documentation emphasizes the “sign in once” expectation. The SDK does not rely on the Vital Sign-In Token for day-to-day operation and API calls. It only needs this artifact once upfront to exchange for the token secrets it needs.

​
Case Study: A typical Backend - Mobile App flow

1

Your app -> Your identity provider

Your end user signs in with your Identity Provider — a separate IdP, or your own API acting as one — through password authentication, Social Login, Single Sign-On (SSO) or any other authentication methods.
2

Your app -> Your backend API

Once your user has successfully authenticated, your app is issued with token secrets for accessing your backend API. Your app stores these token secrets securely.It then makes some API requests to your backend API, in order to gather all information required to setup your app into an authenticated state.Among these API requests, one would be requesting your backend API to issue a Vital Sign-In Token for your authenticated user.
3

Your backend service <-> Junction API

Your backend API receives and validates the token issuance request. Once validated, your backend service:
  • Look up the Vital User associated with this authenticated user;
  • If one does not yet exist, call the Create User endpoint to create a Vital User; and
  • Call the Create Sign-In Token endpoint to obtain a Vital Sign-In Token for this Vital user.
Only this step would use a Junction Team API Key. Because this step happens in your backend service, this enables you to keep the Junction Team API Key strictly as a server-side secret.
curl --request POST
  --url '{{BASE_URL}}/v2/user/{{USER_ID}}/sign_in_token'
  --header 'X-Vital-API-Key: <YOUR-API-KEY>'
Your backend API then responds to your app with the obtained Vital Sign-In Token:
{
  "user_id": "e209947b-323e-4108-8e18-1518b80da0bd",
  "sign_in_token": "XYZ=="
}
4

Your backend API -> Your app

Your app receives a response from your backend API, which includes the Vital Sign-In Token for the authenticated user.Your app then calls the Vital Mobile SDK signIn method with the Vital Sign-In Token:
import VitalCore

let response: MyAPIResponse = // ....

do {
  try await VitalClient.signIn(withRawToken: response.signInToken)

  print("Signed in with Vital successfully")
} catch let error {
  print("Error signing in with Vital", error)
}

signIn() throws an error when you have already signed in with the Vital SDK.You can inspect the Core SDK status at any time for troubleshooting. You can also rely on the Core SDK status to reconcile differences between your own user session state and Vital SDK sign-in.
5

Voila!

The Vital Mobile SDK is now signed-in with the Vital User associated with your authenticated user. You can now proceed to use all the Vital SDK features.

​
Junction Team API Keys

API Key is discouraged for production mobile apps, since it would be distributed as cleartext. API Key support is intended only for customer early evaluation in Sandbox.Use Vital Sign-In Token whenever possible.
Vital Mobile SDK can be configured to authenticate using API Key alongside a target user ID. 
import VitalCore

VitalClient.configure(
  apiKey: "sk_us_...",
  environment: .sandbox(.us)
)
VitalClient.setUserId(UUID(uuidString: "ccd6f98d-3a2a-433b-a114-8fe064f301ed")!)

When running on iOS, the SDK must be explicitly configured before other SDK methods can be invoked.Alternatively, follow the Apple HealthKit guide to enable SDK Automatic Configuration during app launch. This auto-configures the SDK using the last known configuration you supplied — including but not limited to the API Key, the environment and the target User ID. Not only is this a prerequisite to enable HealthKit Background Delivery, this allows you also to only call configure(...) and setUserId(...) once to “sign-in” the user persistently when using the Junction Team API Key scheme.

​
Sign Out

Regardless of the authentication scheme you used, you can sign out with the Vital SDK using signOut(). This erases any persistent user session and configuration stored by the Vital Core and Health SDKs. 
import VitalCore

await VitalClient.shared.signOut()

​
Migrate from Junction Team API Keys to Vital Sign-In Tokens

Always use Vital Sign-In Token for your production mobile apps.
An existing app installation signed-in with Junction Team API Key + User ID can be seamlessly migrated to use Vital Sign-In Tokens. It is as simple as performing a one-off migration logic during app launch:
1

Condition to migrate

Check whether the Vital SDK status includes useApiKey (i.e., the user is signed in using Junction Team API Key).
2

Obtain a Vital Sign-In Token

Similar to the new user sign-in flow, your app needs to obtain a Vital Sign-In Token through your backend service.
3

Sign-in with the token

Your app can simply sign-in with the Vital Sign-In Token.Note that it is unnecessary to reset the SDK beforehand — the SDK signIn method would automatically migrate, as long as the supplied Sign-In Token is compatible with the existing API Key sign-in (i.e., having the same Vital user ID, same Vital environment, and same Vital region).
import VitalCore

if VitalClient.status.contains(.useApiKey) {
  do {
    let response = await callBackend(...)
    try await VitalClient.signIn(withToken: response.signInToken)
  }

    print("Signed in with Vital successfully")
  } catch let error {
    print("Error signing in with Vital", error)
  }
}