Mobile SDK Authentication
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.
General Expectations
The Vital Mobile SDK user session lifecycle is expected to match your own user session lifecycle:
-
When your app has successfully authenticated the user with your backend service, it should begin the process to sign-in with the Vital Mobile SDK.
-
When your user has requested to sign out from your app, it should instruct the Vital Mobile SDK to reset its state.
Your mobile apps typically only need to request the Vital Sign-In Token once through your backend service, and use the obtained Vital Sign-In Token sign-in with the Vital Mobile SDK. Once signed-in, Vital Mobile SDK maintains its user session in persistence storage.
API flow example
Your app -> Your backend
After your app has authenticated with your backend service, your client app detects that Vital Mobile SDK is in signed-out state.
Your app makes a getVitalSignInToken API call to your backend service using your own API authentication method.
Your backend -> Vital API
Your backend service receives and validates the request, and forwards the request to 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>'
Vital API -> Your backend
Vital API creates a new Vital Sign-In Token, and returns it to your backend service. Your backend service includes the Vital Sign-In Token as part of the getVitalSignInToken API response.
Your backend -> Your app
Your app receives the API response and the Vital Sign-In Token. It then signs in with the Vital Mobile SDK using said token.
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)
}
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. Please refer to the specific SDK guide:
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:
Condition to migrate
Check whether the Vital SDK status includes useApiKey (i.e., the user is signed in using Vital API Key).
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.
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)
}
}