--- title: Troubleshooting slug: frameworks/kmi-troubleshooting createdAt: 2026-11-03T06:49:31.174Z --- # Troubleshooting This guide covers **KMI version 1.0**. Compare Sine activity with your service's redacted request and response diagnostics and the cabinet's state. A successful Sine check-in is not, by itself, proof that cabinet access was created or activated. ## Verify Fails **Symptom:** The connection check fails, times out or returns an unexpected response. Check endpoint reachability and authentication using the sections below. Verify must return HTTP `200` with `{ "code": "SUCCESS" }` only after the configured cabinet connection check succeeds. It must not create a cabinet user. If Verify succeeds but another operation fails, investigate that operation separately. Verify does not establish that user creation, selected key groups or permission changes work. ## Sine Cannot Reach an Endpoint | Possible cause | What to check | | ----------------------------------------------- | ----------------------------------------------------------------- | | Incorrect endpoint URL | Confirm that each configured URL points to the intended operation | | Your service is unavailable | Check service health, routing and upstream availability | | TLS certificate is invalid or expired | Install a valid certificate for the endpoint hostname | | A firewall or network policy blocks the request | Allow the approved Sine-to-service connection path | | The request times out | Check service and cabinet latency and review request diagnostics | Use HTTPS and do not disable certificate validation to work around connection problems. ## Endpoint Rejects Authentication | Possible cause | What to check | | ---------------------------------------------------- | -------------------------------------------------------------------------------------- | | KMI API keys do not match | Update the secret in the authorised systems without exposing its value | | The service expects a different header format | Sine sends the configured API key as the `Authorization` value without adding a prefix | | The key is valid but not authorised for the customer | Check the association between the key and `config.externalId` | | Cabinet API credentials are invalid | Check the separate credentials your service uses for the cabinet | Do not confuse the KMI API key with a visitor's cabinet PIN or with the cabinet API credentials. Never include these values in support tickets. ## Key Groups or Keys Are Missing | Possible cause | What to check | | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | Wrong `externalId` | Confirm that it selects the intended customer and cabinet configuration | | Resources response has the wrong shape | Return a top-level `keyGroups` array with stable string IDs and names | | Wrong selected groups | Check the group IDs passed to Keys and their membership in the cabinet | | Cabinet API results are paginated | Retrieve every required page before returning a successful inventory | | Duplicate keys occur across groups | Deduplicate keys by their stable cabinet ID | | A key ID is too long for the Sine asset identifier | Check the site's asset-type prefix and the identifier-length constraint; do not truncate IDs blindly | | Keys response has the wrong shape | Return `SUCCESS` and a complete `data` array of key IDs and names | A successful Keys response is treated as the inventory snapshot. Missing entries may be removed from Sine. If your service cannot retrieve the complete inventory, return an error rather than an empty or partial success. ## Visitor Checks In but No Cabinet User Is Created | Possible cause | What to check | | --------------------------------------- | ------------------------------------------------------------------------------------------- | | Visitor did not select a key | Confirm the check-in form uses the synchronised key list and the visitor selected an option | | No visitor email or mobile was supplied | Provide a supported contact detail; email is needed for credential email | | Provision request is invalid | Check `externalId`, `visitId`, visitor fields, validity and the requested key IDs | | Cabinet user creation failed | Inspect your service's redacted result and cabinet permissions | | Provision response is incomplete | Return `PROVISIONED` with non-empty `data.keyUserId` and `data.password` | | Provision returns the wrong HTTP status | Return HTTP `201`, not `200`, with the required response body | | A request timed out after creation | Reconcile the visit against cabinet records before creating another user | Sine waits for Provision, so a slow service can delay pass creation. A provisioning failure handled by Sine does not, by itself, reject check-in. Check the actual cabinet outcome before retrying. ## Cabinet User Cannot Collect Keys | Possible cause | What to check | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------ | | Pass is pending approval | Wait for the applicable approval; Activate occurs after acceptance | | Activate failed | Check the request, service response and cabinet permission update | | Wrong key IDs were mapped | Use the IDs your service returned from Keys, not Sine asset IDs, and map them to cabinet IDs if needed | | Cabinet validity or permissions are wrong | Check the visitor's time window, key permissions and cabinet policy | | Validity information was not retained | Store the window supplied in Provision; Activate does not repeat `validFrom`, `validTo` or `timezone` | | Visitor is using the wrong credentials | Use the visitor's cabinet user ID and PIN, not the KMI API key | Provision and Activate are separate operations. Do not grant the requested key permissions to every provisioned user before activation. ## Visitor Does Not Receive Credentials | Possible cause | What to check | | -------------------------------------- | ----------------------------------------------------------------------- | | No visitor email was supplied | Collect an email address when the visitor needs emailed credentials | | Activate did not succeed | Resolve the activation failure before investigating credential delivery | | Provision returned missing credentials | Return non-empty `keyUserId` and `password` values | | Email delivery failed | Check the available Sine notification diagnostics | Sine attempts email after successful activation; mobile contact alone does not imply SMS credential delivery. Do not copy a visitor PIN into logs while investigating. ## Key Return Status Is Wrong or Uncertain Compare the requested key IDs and cabinet user ID with the cabinet's custody records and your service's classification rules. - Return outstanding requested key IDs in the top-level `unreturnedKeyIds` array, using the same IDs supplied in the request. - Preserve key IDs exactly, including leading zeroes. - Check how your service handles missing records, incomplete custody data and keys held by another user. - Return an error if your service cannot establish a trustworthy result; do not silently treat an unknown state as a confirmed return. - Involve the site operator when physical cabinet inspection is required. An empty `unreturnedKeyIds` array means that no requested keys are classified as outstanding under the KMI contract. Check-return does not itself update Sine asset assignments. ## Cabinet Access Ends While Keys Are Outstanding Sine schedules deprovision after a 15-minute grace delay and attempts it even if keys remain outstanding or a return check fails. Arrange physical-key recovery with the site operator. Do not assume that access is extended automatically or that a second reminder is sent. ## Cabinet Access Remains After Check-Out | Possible cause | What to check | | ----------------------------------------- | ------------------------------------------------------------------------------------------------ | | The grace period has not elapsed | Allow at least 15 minutes after check-out for the follow-up return check and deprovision attempt | | Deprovision was not received | Check your endpoint diagnostics and the available Sine activity | | Deprovision failed | Check cabinet connectivity, user mapping and permissions | | Your service removed the wrong permission | Review the `externalId`, `keyUserId` and requested-key mapping | | A prior Provision did not succeed | Check whether a valid cabinet user ID was returned and recorded | Escalate access that remains active unexpectedly. ## Requests or Responses Have Unexpected Fields | Symptom | What to check | | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- | | Customer configuration cannot be resolved | Read `config.externalId`, not a top-level `externalId` | | Provision rejects a visitor with one contact detail | Email and mobile are individually optional; at least one must be non-empty | | Later requests have no `visitId` or validity fields | Resolve `keyUserId` within `config.externalId` using the association and validity stored during Provision | | Resources succeeds but no groups appear | Return `keyGroups` at the top level, not under `data` | | Check-return succeeds but the result is not recognised | Return `unreturnedKeyIds` at the top level, not under `data` | | Key or user IDs no longer match | Preserve IDs as strings, including leading zeroes | | Check-return or Deprovision receives no requested keys | Accept an empty `requestedKeyIds` array; Deprovision must still remove the visit's access | Use the [Implementation Guide](docId\:Yhwc63UQsxJo8sMgylSvB) to compare the exact HTTP status, field names and types for the affected operation. ## Duplicate Cabinet Users Appear A repeated Provision request or a timeout after the cabinet accepted a write can leave the outcome uncertain. For Provision, correlate the customer and `visitId` with cabinet records before retrying. Retain the mapping to `keyUserId`: later operations send that user ID, not `visitId`. Implement a documented recovery process and make repeated requests safe where the cabinet supports it. Do not assume a timed-out request had no effect or that requests are delivered exactly once. ## Getting Help Provide your integration support team or Sine contact with: - The customer `externalId`, Sine site and affected pass ID. - The operation, time and timezone. - A request correlation identifier, if one is available. - The HTTP status and a redacted error message. - The expected and observed cabinet state. - Whether the issue occurred during inventory, provisioning, activation, return checking or deprovisioning. Exclude API keys, cabinet passwords, visitor PINs and unredacted personal data.