​
Vital Sign-In Token

Each Vital Sign-In Token is a short-live token which authorizes a Vital Mobile SDK instance to sign in as a specific user.

Persistence

The user session is persistent on the device once signed in, until you reset the SDK, your app is uninstalled, or you have deleted the user through the Vital API.

Access Scope

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

With Vital Sign-In Tokens, your Vital API Keys can be kept strictly as server-side secrets.

​
General Expectations

The Vital Mobile SDK user session lifecycle should match your app’s user session lifecycle:

  1. When your app has signed in the app user, it should sign-in with the Vital Mobile SDK.

  2. When your app user is signing out from your app, it should instruct the Vital Mobile SDK to sign-out as well.

Vital Mobile SDK keeps a persistent user session on the device. This means your app only needs to sign in the user once, by requesting a Vital Sign-In Token through your backend.

Avoid signing in and out every time your app relaunches. Avoid requesting Vital Sign-In Token every time your app relaunches.

​
API flow example

1

Your app -> Your backend

Your app starts by authenticating with your backend. There are many ways to go about this process, either your own email/password method, or some OAuth Social login (e.g. Facebook, Apple, etc). Once your backend successfully authenticates your app, you should make a second request to authenticate the app’s user against Vital - this will in turn allow you to configure the SDK.

2

Your backend <-> Vital API

Your backend service receives and validates the request. It then calls the Vital Create Sign-In Token API using your server-side Vital API Key secret.

curl --request POST
  --url '{{BASE_URL}}/v2/user/{{USER_ID}}/sign_in_token'
  --header 'X-Vital-API-Key: <YOUR-API-KEY>'

You then send the response back to your app:

{
  "user_id": "e209947b-323e-4108-8e18-1518b80da0bd",
  "sign_in_token": "XYZ=="
}
3

Your backend -> Your app

Your app receives the API response and Vital’s sign_in_token. Finally, it signs in with the Vital Mobile SDK using the signIn method:

import VitalCore

let response: MyAPIResponse = // ....

do {
  try await VitalClient.signIn(withToken: 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.

4

Voila!

The Vital Mobile SDK is good to go!

​
Vital 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 Vital 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 Vital 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 Vital 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 Vital 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)
  }
}
InstallationCore SDK