Before you refresh

Backend-issued JWSThe compact JWS the authenticated backend issued for this tenant and device.
Trusted keys onlyThe SDK obtains trusted keys only from the license JWKS endpoint — never ship your own keys.
Secure token handlingKeep access tokens in host-controlled secure memory; never write them to resources, source, logs, diagnostics, or the lease store.

Signed RC2 refresh contract

The host calls POST /api/v1/License/{deviceId}/refresh. The SDK obtains trusted keys only from /api/v1/License/.well-known/jwks, verifies the compact JWS, and binds it to the authenticated tenant and device.

val evaluation = VisionScanSdk.applySignedLicenseJws(
    jws = signedLicenseToken,
    expectedTenantId = tenantId,
    expectedDeviceId = deviceId
)
check(evaluation.isAllowed)

The legacy object-based applySignedLicense surface is permanently denied. Caller-created plans, features, verification flags, and offline windows are never trusted.

Licensed device refreshes entitlement and continues scanning after updated authorization — Refresh keeps authorization current so a licensed device can continue scanning without exposing token or signing internals in the visual model.

When to refresh

Refresh is event-based, not timer-based. Your host should refresh on startup and foreground, and before lease expiry — then close refresh workers on logout.

The SDK re-evaluates the cached entitlement at session creation and frame submission, so a device whose entitlement lapsed will be denied at the next scan attempt, not mid-scan.

Offline behavior

Offline scanning is allowed only inside backend-signed offline-grace claims. The SDK fails closed after grace expiry. No grace duration is published here — the signed claim carries it, and the backend is authoritative for offline-grace state.

Deployment topology

The signing boundary is the line that matters in production: the backend signs, the SDK verifies. Entitlement always originates from backend billing state — never from the device.

Refresh failures

Refresh is denied. What do I check first?

Check the device state in the portal before reinstalling anything. Pending enrollment, payment grace, deactivated, and revoked each explain a different failure to scan. Confirm the licensed quantity still covers the seats in use.

The device was revoked. What happens?

Revocation invalidates the entitlement, so SDK access stops for that device. The action is recorded in the auditable device and administration history. Enroll the device again to restore access — if the device was lost, enroll its replacement and reuse the released seat.

Will going offline buy us more time?

No. Network failure does not extend the signed offline-grace window, and the SDK fails closed after grace expiry. Plan refreshes on startup and foreground so the device enters offline periods with a fresh signed claim.

applySignedLicense does not activate scanning. Why?

The object-based applySignedLicense surface is a deprecated fail-closed compatibility surface — it never activates scanning. Use applySignedLicenseJws with the backend-issued compact JWS, the expected tenant id, and the expected device id.

What should the app show when scanning is denied?

Disable scan controls when entitlement evaluation is denied, and show the provided remediation and correlation id. Keep diagnostics access available, but never expose signed tokens or raw media.

License refresh