Setup

Setup prepares the SDK for runtime operations by establishing backend session context and ensuring a usable client certificate is available for BLE operations.

Authentication in v1

The initial SDK version supports federated token authentication only.

The SDK expects a tokenProvider in configure() that returns a federated token when requested.

Setup flow

What initialize handles

initialize() is safe to call every time SDK features are needed. Internally it:

Validates existing session tokens in secure storage
Refreshes tokens when possible
Calls the configured tokenProvider when re-authentication is needed
Ensures a valid client certificate exists for device operations
Requests a new certificate from the backend when required
Persists and reads access tokens, refresh tokens, and certificates using platform secure storage

Host app requirements

The host app must provide:

A tokenProvider that returns a federated token silently
A strategy for handling temporary setup failures (for example retry, backoff, or user-facing "try again")

The host app does not handle certificate requests, certificate rotation, token refresh, or backend auth sequencing.

Configure example

Kotlin
Swift

BagIdSdk.configure(BagIdConfig(
    apiBaseUrl = "https://api.bagid.com",
    sourceAppKey = "your-issued-client-key",
    tokenProvider = { myAuthService.getFederatedToken() },
))

import BagIdSDK

enum AuthBridge {
    static func federatedToken() async throws -> String {
        fatalError("Implement token retrieval")
    }
}

BagIdSdk.shared.configure(config: BagIdConfig(
    apiBaseUrl: "https://api.bagid.com",
    sourceAppKey: "your-issued-client-key",
    tokenProvider: AuthBridge.federatedToken
))

Initialize example

Kotlin
Swift

val result = BagIdSdk.initialize()

when (result) {
    is InitResult.Authenticated -> { /* continue */ }
    is InitResult.Unavailable -> {
        Log.e("BagID", "Setup unavailable: ${result.reason}")
    }
}

import BagIdSDK

let result = await BagIdSdk.shared.initialize()

switch onEnum(of: result) {
case .authenticated:
    break // continue
case .unavailable(let unavailable):
    print("Setup unavailable: \(unavailable.reason)")
}

Security role of the client certificate

The client certificate issued during setup bridges the online trust established during authentication to the offline BLE channel where the EBT operates.

EBTs have no internet connection. They cannot call the backend to verify whether an app is authorized. The only trust anchor available to the EBT is a Root CA public key embedded in its firmware at the factory. The client certificate — signed by the corresponding Root CA private key on the backend — is an offline-verifiable proof that the backend endorsed this app installation.

Why the certificate alone is not enough

A valid certificate proves backend endorsement but does not prove the backend authorized this particular write to this particular tag. The backend enforces write authorization through a transaction token: a signature over SHA256(GUID || nonce) using the Root CA private key. The EBT verifies the token against its embedded Root CA public key, confirming the backend authorized the write for this specific tag and session. Together, certificate verification and transaction-token verification form the two checks that protect EBT writes.

Certificate issuance gate

The backend only issues certificates to sessions authenticated via platform attestation (App Attest / Key Attestation) or federated identity from a trusted partner IdP. The certificate’s trust level is bounded by the strength of the session that requested it. The sourceAppKey provided during configure() identifies the partner integration for routing and configuration purposes but is not a security factor — it does not gate certificate issuance on its own.