Skip to main content

Device SDK Authentication (DPoP)

The vitalera SDK v2 uses DPoP (Demonstration of Proof-of-Possession) for authentication. This binds tokens to a cryptographic key pair on the device, preventing token theft and replay attacks — critical for medical device software handling protected health information.

How It Works​

  1. Initialization — When you call VitaleraSdk.builder().clientId("your-org-license-key").build(), the SDK generates a DPoP key pair (stored in the Android Keystore or iOS Secure Enclave).
  2. Activation — The SDK sends a DPoP-signed activation request to the vitalera auth service. The server validates the organization license key and returns a DPoP-bound access token along with the organization's entitlements.
  3. Entitlement caching — Entitlements are cached locally for a 7-day offline grace period. The SDK works offline as long as the cached entitlements have not expired.
  4. Automatic refresh — The SDK handles token refresh transparently. You never need to manage tokens manually.

Android (Kotlin)​

val sdk = VitaleraSdk.builder()
    .context(applicationContext)
    .clientId("your-org-license-key")  // Organization license key
    .addProvider("omron")
    .build()                           // suspend: DPoP key gen + activation

iOS (Swift)​

let sdk = try await VitaleraSdk.companion.builder()
    .clientId(clientId: "your-org-license-key")  // Organization license key
    .addProvider(providerName: "omron")
    .build()                                      // async: Secure Enclave key gen + activation

Obtaining a License Key​

Contact sdk@vitalera.com to obtain an organization license key. Each key is tied to a specific organization and determines which provider modules and features are available.

Offline Operation​

The SDK is designed for medical device use cases where internet connectivity may be intermittent. After initial activation:

  • Device scanning and pairing works fully offline.
  • Observation collection from BLE devices works fully offline.
  • Data is cached locally and synced when connectivity is restored.
  • The 7-day grace period allows the SDK to operate without server contact for up to one week.

If the grace period expires without connectivity, the SDK requires re-activation before further operation.

Security Architecture​

LayerMechanism
Key storageAndroid Keystore / iOS Secure Enclave (hardware-backed)
Token bindingDPoP proof ties each token to the device's key pair
Replay preventionEach DPoP proof includes a unique jti and iat timestamp
TransportTLS 1.2+ for all server communication

Next Steps​

Need Help?​

Reach out to support@vitalera.io for SDK authentication assistance.