Implementation gotchas

A cardholder reports they cannot suspend their Google Wallet credential from the app. Your self-service portal's "suspend my badge" button hits an API call that works for Apple Wallet but returns an error for Google. Or the button appears in the UI for both platforms but silently does nothing for Google.

Google Wallet Corporate Badge has no user-initiated suspend or resume path. All lifecycle changes route through the management system (Client Backend → CP). The cardholder cannot disable their credential from the device. This is a Google platform constraint, not an AE or CP limitation.

Gate the self-service suspend/resume UI on wallet type. Show it only for Apple Wallet cardholders. For Google Wallet, surface an admin-contact flow instead. In API code, branch on the credential's wallet platform before calling any user-side lifecycle endpoint.

A provisioning batch that runs fine in testing fails in production at scale. Requests start returning 403 (HID) or 429 (other vendors) within seconds of the batch starting. No individual request exceeds limits — the problem is volume × token request frequency.

Each API call requests a fresh bearer token. Token endpoints have stricter rate limits than the API endpoints themselves. At batch scale, the token endpoint is hit far more than the provisioning endpoint, exhausting the rate limit budget on tokens alone.

Cache bearer tokens and reuse them within their TTL. Implement proactive refresh before expiry rather than reactive re-auth on 401/403. For HID specifically: 50 token requests per 5 minutes per organizationId is the hard cap — at 20 credentials/minute, you'd hit the limit in seconds if you request a token per credential.

Requests to HID Origo return HTTP 403 Forbidden. Your retry logic, which watches for 429 Too Many Requests, does not trigger. Provisioning silently stops — no retries, no dead-letter queue, credentials never issued.

HID Origo returns 403 — not 429 — for two distinct rate limits: (1) the OAuth token endpoint allows 50 requests per 5 minutes per organizationId; (2) Credential Management APIs (POST /passes, PATCH /passes, etc.) allow 5,000 requests per 5 minutes. Standard HTTP retry libraries treat 429 as a throttle signal and 403 as permanent access-denied — so rate-limit 403s are never retried. Both limits surface as identical 403 responses, requiring response-body inspection to distinguish a rate-limit violation from a genuine authorization failure.

Parse the HID error response body and distinguish a rate-limit 403 from a genuine authorization 403 using the vendor error code. Implement exponential backoff keyed on the 403 + rate-limit code, not on 429. Prevent OAuth token rate limiting by caching bearer tokens and reusing them within their TTL instead of requesting a new token per API call. Prevent Credential Management API rate limiting by staying within 5,000 requests per 5 minutes — batch bulk issuance jobs and space out PPPU calls accordingly.

After a service restart or a brief endpoint outage, some credential lifecycle events (issued, suspended, revoked) are missing from your state. Credential states in your system are stale but HID shows the correct state. No errors in your logs during the outage window.

HID Origo delivers lifecycle events as CloudEvents v1.0 via HTTPS POST and does not retry on failure. If your endpoint returns non-2xx or is unreachable, the event is permanently lost. There is no dead-letter queue, replay API, or missed-event recovery path.

Treat CloudEvents as the fast path, not the only path. Build a polling fallback that periodically queries the HID credential status endpoint to reconcile against your internal state. After any outage or restart, trigger a full reconciliation sweep before trusting local state.

The provisioning flow completes API calls with 200 responses but the credential never appears in the user's wallet. No error in your logs. HID's response looks successful at every step.

HID Origo requires a MOB Key (mobility key) to be loaded into the Origo instance before credentials can be encrypted and issued. If the MOB Key is missing, HID may accept the provisioning request but cannot complete credential generation — the failure is deferred and not always surfaced as an error in the API response.

Verify all four onboarding artifacts are active before starting any provisioning: Origo Instance, Service Account, MOB Key, and Application-ID. Test issuance with a canary user during onboarding — don't wait for production load to discover a missing MOB Key.

A customer has existing HID T100 app-based licenses and wants to add Apple Wallet or Google Wallet credentials through AE. The assumption is that both credential types can be managed from the same HID Origo instance. They cannot. Attempting to manage both from a single portal causes commercial and operational conflicts.

HID Origo's T100 (Enterprise, app-based — HID Mobile Access app) and T200 (Wallet — Apple Wallet / Google Wallet) license types run on separate commercial models and separate portal instances. They cannot co-mingle. This is an HID platform constraint, not a configuration choice.

Treat T100 and T200 as entirely separate deployments. If a customer has existing T100 licenses they did not procure through AE, they must work directly with HID to terminate those licenses and negotiate any credit. AE's scope begins with T200 licenses only. Any T100-to-T200 credit conversion is a bilateral matter between the customer and HID — AE is not the right party to broker it and cannot speak to the conversion value or terms.

Mid-deployment, the customer discovers their reader hardware doesn't support the card format chosen at project setup. All provisioned credentials are unusable at their readers. Changing the format requires reprovisioning every credential from scratch — including a new LEGIC project onboarding call.

LEGIC Google Wallet projects require a one-time card format selection (neon or DESFire) at project onboarding. This choice determines the NFC format written to every credential in the project and is not retroactively changeable. DESFire is more widely supported in EU access control readers; neon requires explicit LEGIC-specific reader support.

Confirm reader hardware compatibility with the chosen card format BEFORE initiating the LEGIC project onboarding call. Get the customer's reader make and model, verify DESFire or neon support in the reader's spec sheet, and document the format decision in the project scope. Default to DESFire for EU deployments unless the customer's reader mandates neon.

Provisioning succeeds for Google Wallet but Apple Wallet shows "Wallet assets not found" when the cardholder opens the walletgateway.io provisioning page. The API returns 200 for both Apple and Google provisioning requests. Assets appear to exist in the ABR (art build repository), so the cause is not immediately obvious from the admin side.

When a Wavelynx group is created via the API, Apple wallet assets (card artwork, pass template) must be included in the group creation call alongside Google Wallet assets. If the Apple assets are omitted from the initial group creation API call, they are absent from the API database — even if the same assets are later added to ABR manually. ABR and the Wavelynx API database are separate stores. Adding assets to ABR after the fact does not populate the API database. The walletgateway.io provisioning page reads from the API database and returns "Wallet assets not found" when Apple assets are missing there.

Call the Wavelynx `/update-wallet-assets` endpoint for the affected group_id to populate the Apple wallet assets into the API database. Do not attempt to fix this by re-adding assets to ABR — that is the wrong store. If access to `/update-wallet-assets` is not available, escalate to Wavelynx partner support and reference the affected group_id. Prevention: when creating a new group via the Wavelynx API, always include both Apple and Google wallet assets in the initial creation call — do not create the group with Google-only assets and plan to add Apple assets later.

Your integration works correctly in one tenant but in another, Apple's eventNotification arrives at the wrong endpoint (or not at all). You assumed the destination was fixed based on one vendor's documentation and hard-coded the routing in your integration.

Apple's eventNotification routing is configured at the credential provider level — the destination endpoint depends on how the tenant was configured during CP onboarding. AE's internal diagrams show eventNotification landing at AE NFC Cloud; Wavelynx's documentation shows it landing at Wavelynx. This contradiction is likely tenant-config-dependent, not a documentation error.

Do not hard-code eventNotification routing assumptions from one vendor's documentation and apply them to another. Verify the event routing configuration for each CP deployment separately before go-live. Treat event destination as a per-tenant config value, not a constant.

Installation engineers arrive on-site to find the customer's existing NFC readers don't support Apple ECP 2.x, lack a Google Smart Tap Collector ID, or use 125kHz (HID Prox / EM) — incompatible with any mobile credential at all. Deployment is blocked. Reader replacement adds weeks and budget overrun to the project.

Reader certification requirements (Apple Wallet Access Program / ECP 2.x, Google Smart Tap certification) are not surfaced during the sales or scoping phase. The customer assumes their existing readers are compatible because they're "NFC readers."

Add reader hardware qualification to the discovery call checklist. Collect reader make, model, and firmware version from the customer before scoping. Verify: (1) ECP 2.x support for Apple, (2) Smart Tap + Collector ID for Google, (3) card format compatibility for LEGIC. Reader re-qualification is the most common late-stage deployment blocker — surface it early, not during installation.

A user created via HID Origo v2.2 SCIM is not found when queried via v3.x Pass API — even though both calls succeed and no error is returned. You get an empty result set or a "not found" from v3.x for a user you can see in v2.2.

HID Origo's v2.2 (SCIM-based) and v3.x (Pass-based) API generations use different identity models and different internal identifier spaces. A user record created in one generation does not automatically appear in the other with the expected identifier format.

Pick one API generation and use it exclusively for a given integration. Document the choice in your integration spec. Never mix calls across generations in the same provisioning flow. New integrations should use v3.x (Pass). If migrating from v2.2, plan a user re-enrollment or explicit migration step — don't assume records carry over.

Google Wallet provisioning works in the web/backend flow but credentials never appear in the user's Google Wallet on Android. The Mobile SDK is not bundled in the app. The issue is discovered during QA, not scoping, adding weeks to the timeline for App Store review cycles.

LEGIC Google Wallet provisioning requires a LEGIC-supplied Mobile SDK bundled inside the Android application. The SDK handles the Google Access Platform protocol on-device. Without it, the app cannot complete the provisioning handshake with Google. This is a LEGIC-specific requirement — Apple Wallet does not need an equivalent SDK (iOS handles the protocol natively).

Include the LEGIC Mobile SDK integration in the initial scoping estimate. Factor in: SDK integration work, app rebuild and testing, App Store submission, and ongoing SDK version update obligations. If the customer is doing Apple-only, the SDK requirement doesn't apply — clarify this early to avoid scope confusion.

Requests to the Wavelynx API start returning 401 Unauthorized at seemingly random intervals. Token refresh logic triggered by 401s causes retry storms. The problem is intermittent and does not reproduce on demand.

Wavelynx's public API documentation (v1.0.12) does not specify TTL values for bearer tokens or provisioning links. If you hard-coded an expiry window inferred from another vendor (e.g. HID's documented TTL) or from observed behavior in testing, that window may not hold in production — Wavelynx can rotate tokens on their schedule without notice.

Implement graceful re-auth on every 401 response. Treat every Wavelynx token as potentially short-lived — never assume a TTL window based on analogy or undocumented behavior. If you need a specific TTL guarantee for a long-running batch job, ask Wavelynx directly. Do not infer from undocumented behavior or testing observations.

A cardholder clicks the provisioning link sent to them by email or SMS and sees an error ("link expired" or "invalid token"). The link was generated recently — minutes or hours ago — not days. The user cannot provision their credential without a new link being generated.

Wavelynx web provisioning links have a finite TTL that is not specified in public documentation. The expiry window may be shorter than assumed, especially if the link generation and delivery pipeline has any latency (e.g. email queuing delays).

Generate provisioning links as close to delivery time as possible. Do not pre-generate links in bulk and queue them for delayed delivery. Build a re-send flow so admins can issue a fresh link without reprovisioning the entire credential. Surface a clear "link expired" message to the cardholder with a "request new link" action.

You receive a LEGIC technical document as a .pptx file. Opening it in PowerPoint shows an error: "This file is protected with Information Rights Management." The file cannot be opened, printed, or extracted. You attempt to work from memory of the email context or filename — content reliability is zero.

LEGIC sometimes delivers technical documentation as Microsoft RMS/IRM- encrypted PowerPoint files. These are encrypted against LEGIC's Azure RMS tenant and are unreadable outside that tenant — no workaround exists for the encryption itself.

Immediately contact John Harvey (john.harvey@legic.com) and ask for an unprotected copy of the deck. Alternatively, check the LEGIC extranet (registration required) for an equivalent Application Note. Do not attempt to work from memory or transcribe from a file you cannot open — only the filename and sender metadata can be captured reliably.