Offline Access

Tip

The core principle: Once a digital key has been synchronized to the device, BLE vehicle access works completely offline. No server contact is required at the moment of unlock or lock.

How offline access works

The flinkey BLE access flow is designed for environments where internet connectivity is unreliable or unavailable — underground parking, rural areas, or vehicles in motion.

sequenceDiagram
    autonumber
    actor driver as Driver
    participant app as Partner app
    participant backend as Partner backend
    participant tapkey as Tapkey server
    participant fbox as flinkey BLE Box

    Note over backend,tapkey: Online phase (once)
    backend->>tapkey: Create assignment
    tapkey-->>backend: Webhook confirmed
    app->>tapkey: Sync digital key
    tapkey-->>app: Digital key stored locally

    Note over driver,fbox: Offline phase (repeatable)
    driver->>app: Trigger unlock
    app->>fbox: BLE authenticate + command
    fbox-->>app: Result (lock state, feedback)
    app-->>driver: Show result

    Note over app,tapkey: Background renewal (after lifetime/2)
    app->>tapkey: Renew key (automatic)
    tapkey-->>app: Fresh key stored locally

The online phase happens once — when the app first synchronizes the digital key after an assignment is created. After that, the offline phase can repeat indefinitely within the key’s lifetime without any server contact.

Lifetime and renewal

Two assignment parameters control the offline behavior:

Parameter	Description	Default
lifetime	Validity duration of the digital key in seconds	604800 (7 days)
renewableAfter	Time after which the SDK attempts background renewal	302400 (3.5 days)

How lifetime works

• When the app syncs a digital key, the key is valid for lifetime seconds
• Within this window, BLE access works without any internet connection
• After renewableAfter seconds (half the lifetime by default), the SDK automatically attempts to renew the key in the background — if internet is available
• If renewal succeeds, the lifetime resets — the driver never notices
• If renewal fails (no internet), the key remains valid until the full lifetime expires
• Only after lifetime has fully expired does the app need internet before the next BLE trigger

Timeline example (default 7-day lifetime)

Day 0     : Key synced (online)
Day 0–3.5 : Full offline access, no renewal attempted
Day 3.5   : SDK tries background renewal (if online: success, timer resets)
Day 3.5–7 : If renewal failed: offline access still works
Day 7     : Key expired — online sync required before next trigger

Assignment revocation

Note

Assignments cannot be revoked offline. If the partner backend deletes an assignment, the revocation only takes effect when the app next synchronizes with the Tapkey server. Until then, the locally cached key remains valid and functional.

This is by design — it ensures that a driver is never locked out of a vehicle due to a temporary network issue. The trade-off is that revocation has a propagation delay of up to lifetime - renewableAfter (default: 3.5 days) in the worst case.

Anti-pattern: Online check before BLE trigger

Danger

Do NOT add an online connectivity check or backend status query before allowing BLE access. This is the most common integration mistake and completely destroys the offline capability.

The problem

Some partner implementations add a network call before the BLE trigger — for example, checking whether the assignment is still active on the backend. This means:

• No unlock in underground parking garages
• No unlock in areas with poor mobile coverage
• No unlock during network outages
• Degraded user experience with added latency even when online

Wrong vs. correct implementation

// WRONG: Online check before trigger — destroys offline access
fun unlockVehicle(carId: String) {
    val isActive = backendApi.checkAssignmentStatus(carId)  // BLOCKS OFFLINE
    if (!isActive) {
        showError("No active assignment")
        return
    }
    tapkeySdk.triggerLock(carId, commandData)
}

// CORRECT: Use local key validity only
fun unlockVehicle(carId: String) {
    if (tapkeySdk.hasValidLocalKey(carId)) {
        tapkeySdk.triggerLock(carId, commandData)
    } else {
        showError("No valid key — please connect to internet")
    }
}

The Tapkey Mobile SDK already handles all authorization locally. If a valid digital key exists on the device, the BLE Box will authenticate the request. There is no need — and no benefit — to adding a redundant backend check.

When is internet connectivity required?

Operation	Internet required
First-time key synchronization (after assignment created)	Yes
BLE trigger (unlock / lock / Box Command)	No
Background key renewal (after renewableAfter)	Yes (automatic, background)
Key expired — re-sync before next trigger	Yes
Assignment creation / update / deletion (backend)	Yes (backend-side)
Receiving assignment webhooks (backend)	Yes (backend-side)

Best practices

1. Never gate BLE access on network availability. The SDK’s local key check is sufficient.
2. Sync keys proactively. When the app starts and internet is available, trigger a key sync (PollForNotifications) to keep keys fresh — but do not block the UI on it.
3. Handle expired keys gracefully. If no valid local key exists, inform the user that an internet connection is needed and offer a retry mechanism.
4. Trust the SDK. The Tapkey Mobile SDK manages lifetime tracking, background renewal and local validation internally. Do not reimplement this logic in the partner app.
5. Test offline scenarios. Put the device in airplane mode after the initial key sync and verify that BLE access still works for the full lifetime period.

Test checklist

• BLE access works with device in airplane mode (after initial sync)
• App does not show errors when offline and key is valid
• App correctly reports “key expired” only after full lifetime has passed
• Background renewal works transparently when connectivity returns
• No backend calls block or gate the BLE trigger flow