Partner Integration

This guide is for partner apps integrating the BagID SDK—airlines and other companies embedding BagID in their own mobile applications. It covers onboarding, credentials, device identity, recommended flows, and a pre-production checklist.

For step-by-step code, start with Quickstart. For the managed BLE JSON contract, see Managed BLE Operations.

Onboarding overview

BagID provisions your integration during onboarding. Your partner app:

Links the SDK (Installation)
Configures API URL, sourceAppKey, and a federated token provider
For TRANSFER: loads journey and baggage data (typically BCBP + DCS via the SDK), then launches Managed BLE Operations with a transfer payload
For other managed operations (CLEAR, readouts, nametag, display toggle): launches managed BLE after configure and initialize — no journey load required
Parses result JSON and presents outcomes in your UI

Contact support@bagid.no to start onboarding or request sandbox access.

Credentials and environments

Credential Description

Credential	Description
API base URL	BagID API endpoint for the environment you are targeting. Production is typically `https://api.bagid.com`. Sandbox / UAT URLs are issued by BagID during onboarding—do not assume they match production paths.
`sourceAppKey`	Value sent as the `X-Source-App-Key` header. Identifies your partner app to the BagID backend. One key per app (or per environment, as agreed with BagID).
Federated token	Identity token from your authentication layer (IdP / session). The SDK exchanges it during `initialize()` for an access token and client certificate. The same token (or a fresh one from your `tokenProvider`) is passed when launching managed BLE flows.
Client certificate	Issued automatically by the SDK during a successful `initialize()`. Stored for the session; your app does not manage certificate lifecycle directly. See Setup.

API base URL

BagID API endpoint for the environment you are targeting. Production is typically https://api.bagid.com. Sandbox / UAT URLs are issued by BagID during onboarding—do not assume they match production paths.

sourceAppKey

Value sent as the X-Source-App-Key header. Identifies your partner app to the BagID backend. One key per app (or per environment, as agreed with BagID).

Federated token

Identity token from your authentication layer (IdP / session). The SDK exchanges it during initialize() for an access token and client certificate. The same token (or a fresh one from your tokenProvider) is passed when launching managed BLE flows.

Client certificate

Issued automatically by the SDK during a successful initialize(). Stored for the session; your app does not manage certificate lifecycle directly. See Setup.

Environment checklist

Before UAT or production:

Use the correct API base URL for the environment (sandbox vs production).
Use the sourceAppKey issued for that environment.
Ensure your federated token is accepted by BagID federation for that environment (coordinate with BagID if login fails with InitResult.Unavailable).
Test on physical devices with real BagID tags (BLE does not work fully in the iOS simulator).

Pass these values to BagIdConfig at configure time, and to managed BLE launch parameters (apiBaseUrl, sourceAppKey, federatedToken) per operation.

Federated authentication

The SDK does not implement your login UI. Your partner app:

Authenticates the passenger or agent in your existing identity system.
Supplies a federated token via BagIdConfig.tokenProvider (suspend / async callback).
Calls BagIdSdk.initialize() before journey or BLE operations.

The token provider should return a valid token without user interaction during SDK calls. The SDK may invoke it on first initialize(), when tokens expire, or on HTTP 401 recovery.

If initialize() returns InitResult.Unavailable, surface a clear error in your app and verify token issuance with your IdP and BagID.

Token format and issuance

Property Detail

Property	Detail
Format	A signed JWT (JSON Web Token) issued by your Identity Provider (IdP). The JWT must contain the claims agreed upon during BagID onboarding (typically subject identifier, partner identifier, and expiry).
Who issues it	Your own IdP (e.g. Azure AD, Auth0, Okta, or an in-house auth service). BagID maintains a trust relationship with your IdP — you register the issuer and public key with BagID during onboarding.
Lifetime	Typically 1–8 hours depending on your IdP configuration. Short-lived tokens (≤ 1 hour) are recommended. The SDK may call `tokenProvider` multiple times per session: on first `initialize()`, on HTTP 401 from the BagID API, and on explicit re-initialize. Ensure your `tokenProvider` silently obtains a fresh token from your IdP cache or session without user interaction.
Managed BLE flows	Launch APIs still take a `federatedToken` parameter, but `initialize()` inside the surface reuses a valid stored session when possible and only calls `tokenProvider` (or the launch token wired as provider) when refresh is missing or expired. Implement `tokenProvider` to return a current JWT on demand—not by fetching a new token before every launch.

Format

A signed JWT (JSON Web Token) issued by your Identity Provider (IdP). The JWT must contain the claims agreed upon during BagID onboarding (typically subject identifier, partner identifier, and expiry).

Who issues it

Your own IdP (e.g. Azure AD, Auth0, Okta, or an in-house auth service). BagID maintains a trust relationship with your IdP — you register the issuer and public key with BagID during onboarding.

Lifetime

Typically 1–8 hours depending on your IdP configuration. Short-lived tokens (≤ 1 hour) are recommended. The SDK may call tokenProvider multiple times per session: on first initialize(), on HTTP 401 from the BagID API, and on explicit re-initialize. Ensure your tokenProvider silently obtains a fresh token from your IdP cache or session without user interaction.

Managed BLE flows

Launch APIs still take a federatedToken parameter, but initialize() inside the surface reuses a valid stored session when possible and only calls tokenProvider (or the launch token wired as provider) when refresh is missing or expired. Implement tokenProvider to return a current JWT on demand—not by fetching a new token before every launch.

Debugging `FEDERATION_REJECTED`

InitResult.Unavailable(reason = FEDERATION_REJECTED) means the BagID backend rejected the token your IdP issued. Common causes:

Symptom Action

Symptom	Action
Wrong issuer or audience	Confirm the `iss` and `aud` JWT claims match what BagID expects for your environment. Sandbox and production may differ — coordinate with BagID.
Token issued for wrong environment	Check that the `sourceAppKey` and `apiBaseUrl` match the environment your IdP is configured for.
Token expired before `initialize()` call	Ensure `tokenProvider` returns a freshly obtained token, not a cached one that may be near or past expiry.
IdP public key not registered with BagID	Contact support@bagid.no — BagID needs your IdP’s JWKS endpoint or public key to verify signatures.
Clock skew > ±5 minutes	Verify device clock synchronisation. JWT validation is time-sensitive.

Wrong issuer or audience

Confirm the iss and aud JWT claims match what BagID expects for your environment. Sandbox and production may differ — coordinate with BagID.

Token issued for wrong environment

Check that the sourceAppKey and apiBaseUrl match the environment your IdP is configured for.

Token expired before initialize() call

Ensure tokenProvider returns a freshly obtained token, not a cached one that may be near or past expiry.

IdP public key not registered with BagID

Contact support@bagid.no — BagID needs your IdP’s JWKS endpoint or public key to verify signatures.

Clock skew > ±5 minutes

Verify device clock synchronisation. JWT validation is time-sensitive.

Supported and planned integration paths

Path Journey / baggage Status

Path	Journey / baggage	Status
`BCBP + DCS (recommended)`	`loadJourney(Bcbp)` then `createBaggageTag`	Supported today — Quickstart Steps 3–4
`Airline journey payload`	`loadJourney(AirlinePayload)` when you already have passenger/flight data	Planned partner path — current builds return `UnsupportedOperationException`; see Journey Preparation
`Airline baggage (no DCS)`	`createAirlineBaggage`	Not implemented in current SDK builds — returns `UnsupportedOperationException`. Use `createBaggageTag` or coordinate with BagID for your baggage registration approach.
`Managed BLE (recommended for EBT)`	`TRANSFER`, `CLEAR`, `READ_*`, `SEND_NAMETAG`, `HIDE_TICKET`, `RESTORE_TICKET`	Supported — Managed BLE Operations

BCBP + DCS (recommended)

loadJourney(Bcbp) then createBaggageTag

Supported today — Quickstart Steps 3–4

Airline journey payload

loadJourney(AirlinePayload) when you already have passenger/flight data

Planned partner path — current builds return UnsupportedOperationException; see Journey Preparation

Airline baggage (no DCS)

createAirlineBaggage

Not implemented in current SDK builds — returns UnsupportedOperationException. Use createBaggageTag or coordinate with BagID for your baggage registration approach.

Managed BLE (recommended for EBT)

TRANSFER, CLEAR, READ_*, SEND_NAMETAG, HIDE_TICKET, RESTORE_TICKET

Supported — Managed BLE Operations

Device identity model

Partner apps often confuse three different identifiers. Use this table when building payloads and device registries:

Identifier Example source Use

Identifier	Example source	Use
BLE `deviceId`	Scan event / `DiscoveredEbtBleDevice.deviceId`	Connect and scan. Platform-specific: MAC-style on Android; CoreBluetooth UUID on iOS (stable per phone + peripheral).
`uniqueDeviceId` (tag GUID)	BLE UUID after connect, or your backend device table	Backend attachment, managed payload `data.uniqueDeviceId`, auto-select in Managed BLE Operations. Store in your app after first successful pairing.
`baggageId` / `journeyId`	`Journey` / `BaggageRecord` from `loadJourney` / `createBaggageTag`	TRANSFER payload and backend baggage linkage.

BLE deviceId

Scan event / DiscoveredEbtBleDevice.deviceId

Connect and scan. Platform-specific: MAC-style on Android; CoreBluetooth UUID on iOS (stable per phone + peripheral).

uniqueDeviceId (tag GUID)

BLE UUID after connect, or your backend device table

Backend attachment, managed payload data.uniqueDeviceId, auto-select in Managed BLE Operations. Store in your app after first successful pairing.

baggageId / journeyId

Journey / BaggageRecord from loadJourney / createBaggageTag

TRANSFER payload and backend baggage linkage.

First-time pairing: user picks a tag from the managed scan list; after success, persist uniqueDeviceId with your user/device record.

Registered device: include data.uniqueDeviceId in the TRANSFER (or other) payload so the SDK finds the tag without manual selection.

Implementation flow references

Use these pages for implementation details. This page stays focused on onboarding, credentials, identity, and production readiness.

Need	Go to
First working transfer	Quickstart
Journey and baggage preparation	Journey Preparation
Managed operation payloads and result JSON	Managed BLE Operations
Custody proof behavior	Managed BLE Operations
Advanced protocol sequence	Transfer & Clear operation details

Need

Go to

First working transfer

Quickstart

Journey and baggage preparation

Journey Preparation

Managed operation payloads and result JSON

Managed BLE Operations

Custody proof behavior

Managed BLE Operations

Advanced protocol sequence

Transfer & Clear operation details

The managed BLE surface collects custody proof inside the SDK UI when ownership verification is required. Partner apps do not implement CustodyProofCollector on the full-screen managed path.

Outcome handling

Parse managed result JSON (status, operation, data or code + message):

SUCCESS — update UI; for TRANSFER, check attachmentSuccess and pendingRetry.
FAILURE — show message; use code for logging and support tickets (see error codes).
CANCELLED — user dismissed the flow; return to previous screen.

If pendingRetry is true, the tag display was updated over BLE but HTTP attachment failed. Offer retry or reconcile with your backend per product rules (see FAQ).

Pre-production (UAT) checklist

Use this checklist before go-live. Test on physical Android and iOS devices with production-representative tags.

Area Verify

Area	Verify
Configure / initialize	`initialize()` succeeds with your production-like federated token; certificate issued without errors.
Journey + baggage	BCBP scan (or `AirlinePayload`) loads journey; `createBaggageTag` returns `baggageId`.
TRANSFER (managed)	Full flow: scan or auto-select → custody if required → tag shows correct baggage data → `attachmentSuccess: true`.
CLEAR (managed)	Display cleared; `unlocked: true` when custody applied.
Registered device	TRANSFER with `data.uniqueDeviceId` finds the correct tag without user picking from list.
Custody rejection	Invalid PNR/surname shows retry UX inside managed flow; valid proof proceeds.
`pendingRetry`	Simulate or observe attachment failure after BLE write; app handles retry messaging.
Permissions	BLE permission denied, Bluetooth off, and airplane mode — partner app shows helpful guidance.
Session expiry	Background app / expired token: `initialize()` or re-launch recovers or surfaces clear error.
Cross-platform	Same payload JSON produces equivalent outcomes on Android and iOS.

Configure / initialize

initialize() succeeds with your production-like federated token; certificate issued without errors.

Journey + baggage

BCBP scan (or AirlinePayload) loads journey; createBaggageTag returns baggageId.

TRANSFER (managed)

Full flow: scan or auto-select → custody if required → tag shows correct baggage data → attachmentSuccess: true.

CLEAR (managed)

Display cleared; unlocked: true when custody applied.

Registered device

TRANSFER with data.uniqueDeviceId finds the correct tag without user picking from list.

Custody rejection

Invalid PNR/surname shows retry UX inside managed flow; valid proof proceeds.

pendingRetry

Simulate or observe attachment failure after BLE write; app handles retry messaging.

Permissions

BLE permission denied, Bluetooth off, and airplane mode — partner app shows helpful guidance.

Session expiry

Background app / expired token: initialize() or re-launch recovers or surfaces clear error.

Cross-platform

Same payload JSON produces equivalent outcomes on Android and iOS.

Support and escalation

For integration questions, sandbox access, or defects:

Email: support@bagid.no
Include: SDK version, platform (Android/iOS), operation (TRANSFER, etc.), environment (sandbox/production), result JSON or error code, tag model/firmware if known, and steps to reproduce.