Bytekey QR Sync

Bytekey QR sync lets a ByteGate Edge appliance validate Bytekey-issued QR credentials locally from a scoped snapshot. It is for customer access at the door, not for Bytekey administration.

Production Contract

• Production sync uses GET /v1/edge/qr-credentials/snapshot on the Bytekey API.
• The edge authenticates with an edge-scoped bearer credential. Use one credential per device or per location, bound server-side to the Bytekey organization/app scope and, where available, the ByteGate tenant/location scope.
• Edge appliances must never store or use Bytekey INTERNAL_AUTH_TOKEN, INTERNAL_DOCS_TOKEN, BYTEGATE_AUTH_TOKEN, or any broad internal/operator token.
• Request headers such as X-Bytegate-Device-Id and X-Bytegate-Location-Id are consistency checks. They do not widen the credential scope.
• Production snapshots include only allocated, unrevoked, unexpired credentials.
• Production snapshots exclude available QR pool credentials.
• Snapshots are cached locally and replaced atomically so a failed or invalid download does not destroy the last known-good cache.
• When enabled, the Edge QR sync manager refreshes the snapshot at service startup and periodically afterwards.

Enablement Path

Bytekey QR sync is disabled by default. Do not turn it on just because a device has been updated to a release that contains the feature.

Before enabling a device:

1. Deploy the Bytekey API version that serves /v1/edge/qr-credentials/snapshot.
2. Provision an edge-scoped QR sync credential in Bytekey API configuration or the registration store used for the rollout.
3. Install or update ByteGate Edge to a release that contains the disabled bytekey_qr_sync config block.
4. Set the Bytekey API base URL, token source, device ID, location ID, cache directory, and timeout in the device configuration.
5. Restart the edge service and confirm the next heartbeat reports bytekey_qr_sync_v1 and healthy bytekey_qr_sync state.

The edge must validate only allocated and unexpired credentials from a fresh snapshot. Once validUntil has passed, Bytekey QR access fails closed until a fresh valid snapshot is accepted. Existing non-Bytekey access paths keep their own behavior.

Dashboard Checks

Open Locations → device → Maintenance and check the Bytekey QR Sync panel.

The dashboard displays:

• whether the device advertises bytekey_qr_sync_v1;
• bytekey_qr_sync status from heartbeat;
• snapshot ID, snapshot age, and validUntil when available;
• readiness and the reason a device is not ready;
• last error text, bounded for operator display.

Generic edge software rollout creation is not blocked by Bytekey QR readiness. This avoids blocking the rollout that introduces bytekey_qr_sync_v1 in the first place. QR-specific enablement should use the readiness helper as the gate.

Rollout Order

Use this order for production:

1. Deploy Bytekey API support first.
2. Ship ByteGate Edge with bytekey_qr_sync still disabled by default.
3. Enable one internal or staging edge and observe snapshot health.
4. Enable one controlled production location.
5. Expand by small cohorts after heartbeat health stays fresh and access logs look normal.

Do not enable a cohort if the maintenance panel shows missing capability, disabled, stale, offline, auth failed, scope mismatch, or error state.

Troubleshooting

Useful checks on the Pi:

cd ~/bytegate-edge
sudo systemctl status bytegate-edge
sudo journalctl -u bytegate-edge -n 120 --no-pager | grep -iE "bytekey|qr|snapshot|auth|scope|stale|offline|error"
grep -n "bytekey_qr_sync" config_production.yaml

Do not paste QR credentials, bearer tokens, or full snapshot files into support tickets. Share status, snapshot age, validUntil, device ID, location ID, and redacted log lines.