Do's and don'ts

Operational guidance drawn from integration experience, vendor documentation, and lessons learned in the field. Filter by kind, vendor, or role to find what's relevant to your current task.

20 entries9 do's8 don'ts4 critical

Kind

Vendor

Role

✗

Don'tCriticalgoogle WalletPre-sales

Don't promise Google Wallet users can suspend their own credential

Google Wallet has no user-initiated suspend or resume path. The cardholder cannot disable their credential from the device without admin action. All lifecycle changes on Google Wallet route through the management system (Client Backend → LEGIC Google Access Hub or equivalent). This contrasts with Apple, where the user can invoke iCloud Lost Mode or Find My to suspend. In pre-sales, customer training, and marketing materials, only promise self-service lifecycle management for Apple Wallet deployments.

✗

Don'tCriticalgoogle WalletPre-sales

Don't promise Google Wallet users can self-provision without admin action

Google Wallet Corporate Badge does not support user-initiated provisioning. The cardholder cannot open Google Wallet and add a credential on their own — they receive a provisioning token pushed by the management system (Client Backend → Mobile App). This is a Google platform constraint, not an AE or CP limitation. Any demo or proposal that shows a user "adding" a Google Wallet credential without an admin-side trigger is misleading. Apple Wallet does support user-initiated provisioning.

✓

DoCriticalHIDEngineering

Cache HID Origo bearer tokens within their idle window

HID Origo's auth endpoint enforces a rate limit of 50 requests per 5 minutes per organizationId. Token fetching against this limit is not optional overhead — it's a hard constraint that will throttle high-throughput provisioning flows if you request a new token per API call. Cache the bearer token and reuse it across requests within its TTL. Implement proactive refresh before expiry rather than reactive re-auth on 401. In tests, a provisioning burst that requests a new token per credential will hit the limit within seconds on large batches.

OAuth — rate limits, 50 req/5 min per organizationId

✓

DoCriticalHIDEngineering

Implement a polling fallback for HID Origo CloudEvents

HID Origo delivers lifecycle event notifications as CloudEvents v1.0 via HTTPS POST to your registered webhook endpoint. Critically: HID does NOT retry failed webhook deliveries. If your endpoint is down, overloaded, or returns a non-2xx response, the event is lost — there is no dead-letter queue or replay API. Build a polling fallback: periodically query the credential status endpoint to reconcile against your internal state. Treat CloudEvents as a fast path, not the only path.

Events/Callbacks — no retry behavior documented

✗

Don'tImportantEngineering

Don't assume Apple eventNotification semantics are consistent across CPs

AE's internal diagrams show eventNotification from Apple landing at AE NFC Cloud; Wavelynx's own documentation shows it landing at Wavelynx. This contradiction is likely tenant-config-dependent — the destination is configured at the credential provider level. The implication: don't write integration code that hard-codes where Apple's eventNotification will arrive based on one vendor's documentation and assume it applies to another. Verify the event routing for each CP separately. This is an open question in the wiki source set (see Open Question #4).

✗

Don'tImportantHIDEngineering

Don't assume HID Origo rate-limit responses use HTTP 429

HID Origo returns HTTP 403 (Forbidden) — not 429 (Too Many Requests) — when a rate limit is exceeded. Standard retry logic that checks for 429 will silently treat HID rate-limit errors as permanent authorization failures and not retry. Parse the HID error response body to distinguish a rate-limit 403 from a genuine auth 403. Implement exponential backoff keyed on the 403 + rate-limit error code, not on 429.

OAuth — rate limit error response format

✗

Don'tImportantHIDEngineering

Don't mix HID Origo v2.2 (SCIM) and v3.x (Pass) API calls in the same flow

HID Origo runs two parallel API generations: v2.2 (SCIM-based, legacy) and v3.x (Pass-based, current). They have different auth flows, different entity models, and different endpoint structures. Pick one path explicitly for a given integration and document which version you chose. Mixing calls across versions in the same provisioning flow creates subtle bugs — a user record created via v2.2 SCIM won't appear in v3.x pass queries with the expected identifiers.

API overview — v2.2 SCIM vs v3.x Pass paths

✗

Don'tImportantLEGICEngineering

Don't assume LEGIC wallet keys share a master with physical card keys

LEGIC's wallet credential encryption keys are architecturally independent of physical card encryption keys — this is an explicit LEGIC design decision. Wavelynx and HID both derive per-credential keys from a master that's also used for physical-card encryption; LEGIC does not. If you're documenting key compromise blast radius, threat modelling a deployment, or advising on side-by-side physical+wallet rollouts, do NOT apply the Wavelynx/HID shared-key assumption to LEGIC. The blast radius is smaller — a LEGIC wallet key compromise doesn't expose physical card keys, and vice versa.

Q2 — key independence confirmation

✗

Don'tImportantLEGICPre-sales

Don't propose HSM-wrapped key import to LEGIC

LEGIC does not support HSM-wrapped key import in the way Wavelynx uses GCP KMS wrapping. LEGIC's Orbit path generates keys inside LEGIC's own HSMs; the customer-supplied path accepts keys via API or ceremony — neither maps to "bring your own HSM-wrapped key blob." If a customer or prospect asks about BYOK (bring your own key) in the HSM-import sense, clarify that LEGIC's options are Orbit (LEGIC-managed HSM) or customer-supplied key (manual process), not a wrapped-key-blob import.

Q2 — key management options

✓

DoImportantPre-sales

Verify reader certification before scoping any wallet deployment

Both Apple Wallet and Google Wallet require certified reader hardware — Apple via the Wallet Access Program, Google via Smart Tap certification. Not all NFC readers support both. Before scoping a deployment, confirm: (1) does the customer's existing reader hardware support Apple ECP 2.x? (2) does it have a Google Smart Tap Collector ID? (3) if adding LEGIC, does it support the selected card format (neon or DESFire)? Reader re-qualification is a common late-stage blocker — surface it in the discovery call, not during deployment.

✓

DoImportantHIDIntegrator

Complete all HID Origo onboarding prerequisites before PMO kickoff

A HID Origo integration requires four distinct provisioned artifacts before any credentials can be issued: (1) Origo Instance — the tenant-level configuration; (2) Service Account — the credential AE uses to authenticate; (3) MOB Key — the mobility key loaded into Origo for credential encryption; (4) Application-ID — the per-wallet-app identifier. All four must be active before PMO begins. Missing any one blocks issuance entirely. Start the HID onboarding process at least 2 weeks before the planned integration start date — HID's provisioning SLA for new accounts is not instantaneous.

Onboarding — instance, service account, MOB key, application ID

✓

DoImportantLEGICIntegrator

Use LEGIC Orbit for key management

LEGIC offers two key management paths: customer-supplied keys (via API or key ceremony) and LEGIC Orbit (HSM-backed, keys generated inside LEGIC's HSMs and never exposed in plaintext). Always recommend Orbit for new deployments. Orbit is the only path that supports key rotation — and key rotation is not optional for any deployment with a compliance requirement. Customer-supplied keys trade control for operational burden and lose the rotation path entirely.

Q2 — Orbit recommended; Q4 — rotation only on Orbit path

✓

DoImportantLEGICgoogle WalletIntegrator

Account for the LEGIC Mobile SDK in Android app builds for Google Wallet

LEGIC Google Wallet provisioning requires a LEGIC-supplied Mobile SDK bundled inside the Android app. This SDK handles the Google Access Platform protocol on-device and is not optional. Factor SDK integration into mobile app build timelines, App Store review cycles, and SDK version update obligations. Apple Wallet does not require an equivalent SDK — the iOS system handles the Apple Credential Provider protocol natively. If a customer is doing Apple-only, the SDK question doesn't apply.

Slide 2 — Mobile SDK in Mobile App actor

✓

DoImportantLEGICgoogle WalletIntegrator

Confirm neon vs DESFire before starting LEGIC Google Wallet onboarding

LEGIC Google Wallet projects require a card format selection at onboarding: neon (LEGIC's proprietary NFC format) or DESFire (NXP MIFARE DESFire). This choice is made once at project setup and determines reader compatibility across the entire deployment. DESFire is more widely supported in EU access control reader hardware. Get this decision locked before initiating the LEGIC project onboarding call — changing it later may require reprovisioning all credentials.

Slide 2 step 1 — neon or DESFire format selection

✗

Don'tRecommendedWavelynxEngineering

Don't rely on Wavelynx publicly documenting token TTLs

Wavelynx's public API documentation (v1.0.12) does not specify TTL values for bearer tokens or provisioning links. Don't hard-code assumptions about expiry windows based on analogy with HID or LEGIC. Implement graceful re-auth on 401 and treat every token as potentially short-lived. If a specific TTL is required for your integration design (e.g., for a long-running batch job), ask Wavelynx directly — don't infer from undocumented behavior.

Token TTL — not specified

✓

DoRecommendedLEGICIntegrator

Ask LEGIC for unprotected copies of IRM-encrypted slide decks

LEGIC's technical documentation is sometimes delivered as Microsoft RMS / IRM-encrypted PowerPoint files. These are unreadable outside LEGIC's Azure RMS tenant and cannot be extracted or processed programmatically. When LEGIC sends a protected PPTX: immediately ask John Harvey (john.harvey@legic.com) for an unprotected copy, or check the LEGIC extranet (registration required) for an equivalent Application Note. Do not attempt to manually transcribe content from a deck you can't open — the metadata (filename, sender, license principals) can be captured but the content cannot be trusted as accurate from memory.

IRM-protected PPTX handling discipline — Decision

✓

DoRecommendedPre-sales

Quote 20–30 seconds as average end-to-end provisioning time

Across Wavelynx, HID, and LEGIC, the typical end-to-end provisioning time — from user tapping "Add to Wallet" to credential available on device — is 20–30 seconds. LEGIC confirmed this range for their implementation. Use this figure in demos, pre-sales conversations, and customer training. Set user expectations before the demo: the wait is normal, not a sign of an error. Don't promise sub-5-second provisioning; the Apple and Google wallet platform round-trips alone account for most of the delay.

Q6 — 20–30 second provisioning time estimate

ConsiderRecommendedLEGICPre-sales

Lead with LEGIC's key independence for EU and regulated deployments

In EU enterprise deployments where physical and mobile credentials coexist, LEGIC's independent key architecture is a meaningful differentiator. A wallet credential compromise does not expose the physical card key material, and rotation of wallet keys doesn't touch the physical card infrastructure. For customers in regulated sectors (finance, critical infrastructure, healthcare) who ask about blast radius or key rotation cadence, this is worth surfacing explicitly — it's not the default assumption they'll bring from Wavelynx or HID experience.

Q2 — key architecture

ConsiderInformationalLEGICPre-sales

Check OSS-SO Wallet extension support for EU access control deployments

EU enterprise customers in the access control space frequently ask whether mobile credentials are compatible with their existing OSS-SO (Open Security Standards — Standard Offline) infrastructure. LEGIC Connect supports payloads formatted per the latest OSS-SO Wallet extension. OSS-SO Parts II and III support is an open question. When qualifying an EU deal involving offline locks or a mixed card/mobile environment, ask explicitly: does the customer's lock vendor require OSS-SO interop? If yes, LEGIC is currently the strongest answer — HID and Wavelynx OSS-SO status is unknown.

Q1 — OSS-SO Wallet extension supported

ConsiderInformationalIntegrator

Consider web provisioning path when mobile app rollout lags credential issuance

Wavelynx and HID both support web-based provisioning — the cardholder receives a link, opens it in a browser on any device, and the credential is added to their phone's wallet. This is useful when the customer's mobile app isn't ready, or when a subset of employees won't install the app. Web provisioning adds a redirect step and may have different Apple / Google platform auth requirements, but removes the dependency on a fully deployed native app. LEGIC's web path is not confirmed in current sources — verify before proposing.

20 of 20 entries shown