API Reference

The SDK exposes a single entry point: the BagIdSdk object. All operations are static methods on this object.

On iOS, Kotlin object BagIdSdk is exposed as BagIdSdk.shared (singleton). SKIE generates Swift-friendly async APIs. Generated Swift signatures can vary by SDK build, so examples below show the typical call shape.

Integrate through BagIdSdk only: one HTTP session (after successful initialize()), one BLE façade (scanForEbtTags, connectEbt, …), and merged state in BagIdState.

BagIdSdk

Kotlin
Swift

object BagIdSdk {
    fun configure(config: BagIdConfig)
    suspend fun initialize(): InitResult
    suspend fun loadJourney(request: LoadJourneyRequest): Result<Journey>
    suspend fun createBaggageTag(request: CreateBaggageTagRequest): Result<Journey>
    suspend fun createAirlineBaggage(request: CreateAirlineBaggageRequest): Result<Journey>
    val state: StateFlow<BagIdState>
    val ebtBleDeviceState: StateFlow<EbtBleDeviceState>
    fun scanForEbtTags(): Flow<BagIdScanEvent>
    fun scanForEbtTags(deviceId: String): Flow<BagIdScanEvent>
    fun notifyDiscoveredModel(device: DiscoveredEbtBleDevice)
    suspend fun connectEbt(deviceId: String): Result<Unit>
    suspend fun disconnectEbt(): Result<Unit>
    suspend fun writeEbtTicket(ticket: EbtTicket, transferLogLabel: String? = null): Result<Unit>
    suspend fun clearEbtDisplay(): Result<Unit>
    suspend fun readEbtBattery(): Result<Int>
    suspend fun readEbtFirmware(): Result<String>
    fun ebtBleExtras(type: EbtType): EbtBleExtras
    suspend fun transferTag(request: TransferTagRequest): Result<TransferResult>
    suspend fun clearTag(request: ClearTagRequest): Result<ClearResult>
    fun onSessionExpired(listener: () -> Unit)
}

import BagIdSDK

// Typical call shape:
BagIdSdk.shared.configure(config: config)
let initResult = await BagIdSdk.shared.initialize()
let journey = try await BagIdSdk.shared.loadJourneyOrThrow(request: request)
for await event in BagIdSdk.shared.scanForEbtTags() { _ = event }
for await ble in BagIdSdk.shared.ebtBleDeviceState { _ = ble }
let transfer = try await BagIdSdk.shared.transferTagOrThrow(request: transferRequest)
for await sdkState in BagIdSdk.shared.state { _ = sdkState }

configure

Kotlin
Swift

fun configure(config: BagIdConfig)

// Typical call shape:
BagIdSdk.shared.configure(config: config)

Sets the SDK configuration. Call once at app startup before initialize().

Parameter Type Description

Parameter	Type	Description
`config`	`BagIdConfig`	API endpoint, client key, token provider, optional theme and localization. See BagIdConfig.

config

BagIdConfig

API endpoint, client key, token provider, optional theme and localization. See BagIdConfig.

initialize

Kotlin
Swift

suspend fun initialize(): InitResult

// Typical call shape:
let result = await BagIdSdk.shared.initialize()

Authenticates with the backend using the configured tokenProvider, obtains an access token and client certificate for this session, and updates BagIdState.

Returns InitResult.Authenticated on success, or InitResult.Unavailable(reason) if configuration is missing, the token provider fails, federation is rejected, or certificate issuance fails.

Each successful call replaces the active HTTP session (previous repositories are closed). Safe to call from a cold start or after configuration changes; it does not silently skip work based only on cached tokens—you get a fresh login + certificate for the returned token.

loadJourney

Kotlin
Swift

suspend fun loadJourney(request: LoadJourneyRequest): Result<Journey>

// Typical call shape:
let journey = try await BagIdSdk.shared.loadJourneyOrThrow(request: request)

Loads a journey from a BCBP barcode or airline-supplied payload.

Variant Description

Variant	Description
`LoadJourneyRequest.Bcbp(scanData: String, airline: String?)`	Journey from a BCBP / scan string. `airline` is optional.
`LoadJourneyRequest.AirlinePayload(passengers: List<AirlinePassenger>)`	Journey from airline-supplied passenger data without a BCBP scan.

LoadJourneyRequest.Bcbp(scanData: String, airline: String?)

Journey from a BCBP / scan string. airline is optional.

LoadJourneyRequest.AirlinePayload(passengers: List<AirlinePassenger>)

Journey from airline-supplied passenger data without a BCBP scan.

Returns a Journey with journey ID, passengers, flights, and any existing baggage.

The SDK returns data models only. The host app is responsible for presenting the journey response to the user and guiding the user to the next step (e.g. baggage tag generation), including clear messaging for backend limitations or errors.

createBaggageTag

Kotlin
Swift

suspend fun createBaggageTag(request: CreateBaggageTagRequest): Result<Journey>

// Typical call shape:
let updated = try await BagIdSdk.shared.createBaggageTagOrThrow(request: request)

Generates a baggage tag via DCS for the specified journey and passengers.

Returns the updated Journey with populated baggage records including baggageId.

createAirlineBaggage

Kotlin
Swift

suspend fun createAirlineBaggage(request: CreateAirlineBaggageRequest): Result<Journey>

// Typical call shape:
let updated = try await BagIdSdk.shared.createAirlineBaggageOrThrow(request: request)

Creates a baggage record from airline-supplied tag data (no DCS).

Returns the updated Journey with the new baggage record including baggageId.

scanForEbtTags

Kotlin
Swift

fun scanForEbtTags(): Flow<BagIdScanEvent>
fun scanForEbtTags(deviceId: String): Flow<BagIdScanEvent>

for await event in BagIdSdk.shared.scanForEbtTags() { _ = event }
for await event in BagIdSdk.shared.scanForEbtTags(deviceId: "device-id") { _ = event }

Cold flow of BagIdScanEvent. Starting collection starts scanning; cancelling stops it. The deviceId overload filters to one peripheral.

The host provides discovery UI. Call notifyDiscoveredModel when the user picks a row, then connectEbt. Only one active scan collector should run at a time.

Different tags can use different BLE protocols internally; the SDK picks the right one from scan data. After connectEbt, you use the same ticket/clear/read and transferTag / clearTag APIs without choosing a stack in app code.

ebtBleDeviceState

Kotlin
Swift

val ebtBleDeviceState: StateFlow<EbtBleDeviceState>

for await s in BagIdSdk.shared.ebtBleDeviceState { _ = s }

Full BLE transport snapshot (ConnectedEbtDevice, transport errors). BagIdState duplicates a shorter summary plus bleLastError.

notifyDiscoveredModel

Kotlin

fun notifyDiscoveredModel(device: DiscoveredEbtBleDevice)

Call with the user-selected discovery row before connectEbt so BagIdState.identifiedEbtTagIdentity matches the choice.

connectEbt

Kotlin
Swift

suspend fun connectEbt(deviceId: String): Result<Unit>

let r = await BagIdSdk.shared.connectEbt(deviceId: id)

Connects using cached discovery metadata for deviceId. Requires prior scan and notifyDiscoveredModel when the user selects from the list.

disconnectEbt

Kotlin

suspend fun disconnectEbt(): Result<Unit>

Drops the active EBT link (no-op if none).

writeEbtTicket

Kotlin

suspend fun writeEbtTicket(ticket: EbtTicket, transferLogLabel: String? = null): Result<Unit>

Writes display data over BLE. Requires connection.

clearEbtDisplay

Clears the tag display over BLE (no HTTP unlock). Production clear with backend unlock is clearTag.

Kotlin

suspend fun clearEbtDisplay(): Result<Unit>

readEbtBattery

Kotlin

suspend fun readEbtBattery(): Result<Int>

Returns 0–100 when supported.

readEbtFirmware

Kotlin

suspend fun readEbtFirmware(): Result<String>

ebtBleExtras

Kotlin

fun ebtBleExtras(type: EbtType): EbtBleExtras

Optional vendor-specific BLE features beyond the core façade (pattern: pick EbtType, use the returned interface). Nametag via sendNametag is one example for EbtType.BagId. Requires connection. See models.

transferTag

Kotlin
Swift

suspend fun transferTag(request: TransferTagRequest): Result<TransferResult>

// Typical call shape:
let transfer = try await BagIdSdk.shared.transferTagOrThrow(request: request)

Orchestrates BLE connect (if needed), lock lookup, custody proof when required, authorize, BLE ticket write, then device attachment.

If custody proof is required and recordLocator / custodyProofSurname are missing, the call fails with CustodyProofRequiredException and hints—collect PNR and surname in your UI and retry. See TransferTagRequest.

See Transfer & Clear for the sequence diagram.

clearTag

Kotlin
Swift

suspend fun clearTag(request: ClearTagRequest): Result<ClearResult>

// Typical call shape:
let clear = try await BagIdSdk.shared.clearTagOrThrow(request: request)

Clear with backend authorize, BLE clear, and unlock. ClearTagRequest needs both deviceId (BLE) and uniqueDeviceId (backend). See transfer.adoc#_clearing_an_ebt.

state

Kotlin
Swift

val state: StateFlow<BagIdState>

// Typical call shape:
for await sdkState in BagIdSdk.shared.state { _ = sdkState }

Observable façade: auth, session flags, connected device summary, lastError, bleLastError, identified tag identity. See BagIdState.

onSessionExpired

Kotlin
Swift

fun onSessionExpired(listener: () -> Unit)

// Typical call shape:
BagIdSdk.shared.onSessionExpired {
    // navigate to host-app login flow
}

Registers a listener invoked when the SDK’s session expires and the token provider also fails. The host app should navigate to its own login flow and call initialize() again after re-authentication.