--- title: Quick Reference slug: frameworks/kmi-quick-reference createdAt: 2026-11-03T06:49:31.258Z --- # KMI Reference This is the consolidated reference for **KMI version 1.0**. Implement seven HTTPS endpoints in your integration service. A Sine administrator configures the endpoint URLs, KMI API key, customer `externalId` and selected key groups. ## Operation Summary | Operation | Sine lifecycle trigger | Success response | | ------------ | --------------------------------------------------- | --------------------------------------------------------------- | | Verify | Connection check | `200`, `code: "SUCCESS"` | | Resources | Key-group selection | `200`, top-level `keyGroups` | | Keys | Inventory sync | `200`, `code: "SUCCESS"` and `data` array | | Provision | Pass creation with requested keys | `201`, `code: "PROVISIONED"` and non-empty user ID and password | | Activate | Check-in or pass acceptance | `200`, `code: "ACTIVATED"` | | Check-return | Check-out and follow-up return check | `200`, `code: "SUCCESS"` and top-level `unreturnedKeyIds` | | Deprovision | Pass rejection or end of the check-out grace period | `200`, `code: "DEPROVISIONED"` | All seven operations use `POST` with JSON. The endpoint URLs are configured separately; example paths in these guides are illustrative. ## Authentication ```http Authorization: Content-Type: application/json Accept: application/json ``` The `Authorization` value is the KMI API key configured in Sine. Sine sends it as configured, without automatically adding `Bearer`. Your service authenticates Sine using that key and stores its cabinet API credentials separately. Use HTTPS and issue a separate API key per customer integration. Authenticate the key on every operation and check that it is authorised for the supplied `externalId`; reject a mismatch with `403`. ## Consolidated Request Field Reference ### Common Configuration | Field | Requirement | Purpose | | -------------------- | --------------------------------------------------------------- | -------------------------------------------- | | `config` | Required object on every operation | Contains the configuration fields below | | `config.externalId` | Required non-empty string | Select the customer or cabinet configuration | | `config.keyGroupIds` | Non-empty string array for Keys; may appear on other operations | Selected cabinet key-group IDs | Your service owns the cabinet connection details and credentials. Preserve all customer, group, key and user identifiers as strings, including leading zeroes. The Sine asset identifier limit is 100 UTF-16 code units including its type prefix, `::` separator and key ID; overlong key IDs are skipped. ### Provision-Only Fields | Field | Type | Requirement and meaning | | --------------------------------------- | ------- | --------------------------------------------------------- | | `visitId` | string | Required, non-empty Sine pass ID | | `visitor` | object | Required visitor details | | `visitor.firstName`, `visitor.lastName` | strings | Required, non-empty visitor names | | `visitor.email`, `visitor.mobile` | strings | Individually optional; at least one must be non-empty | | `validFrom`, `validTo` | strings | Required visit validity timestamps in ISO 8601 UTC format | | `timezone` | string | Required, non-empty site timezone | Your [Provision endpoint](#) must return the KMS-issued cabinet user ID in `data.keyUserId` and the visitor's cabinet password or PIN in `data.password`. Both are required non-empty response strings; Sine does not supply these credentials in the request. The password is a visitor cabinet credential, not the KMI API key. ### Key and User Fields The common configuration object is also included on these operations. | Field | Operations | Type | Requirement and meaning | | ----------------- | ----------------------------------- | ---------------- | --------------------------------------------------------------- | | `keyUserId` | Activate, Check-return, Deprovision | string | Required, non-empty cabinet user ID returned by Provision | | `requestedKeyIds` | Provision, Activate | array of strings | Required, non-empty array of non-empty key IDs returned by Keys | | `requestedKeyIds` | Check-return, Deprovision | array of strings | Required; may be empty, but each supplied ID must be non-empty | Check-return returns only requested IDs considered outstanding in a top-level `unreturnedKeyIds` array. If custody state cannot be determined, return an error rather than an empty success. Activate, Check-return and Deprovision do not include `visitId`, `validFrom`, `validTo` or `timezone`. Store the `externalId`/`visitId` to `keyUserId` association and cabinet validity information during Provision. ## Consolidated Response Field Reference All fields below are required for their operation. | Field | Operation | Type | Meaning | | ------------------------------------ | -------------------------- | ---------------- | ------------------------------------------------------------- | | `code` | Verify, Keys, Check-return | string | `SUCCESS` | | `code` | Provision | string | `PROVISIONED` | | `code` | Activate | string | `ACTIVATED` | | `code` | Deprovision | string | `DEPROVISIONED` | | `keyGroups` | Resources | array of objects | Available groups; may be empty; no `code` wrapper | | `keyGroups[].id`, `keyGroups[].name` | Resources | strings | Stable group ID and display name | | `data` | Keys | array of objects | Complete selected inventory; may be empty | | `data[].id`, `data[].name` | Keys | strings | Stable key ID and display name | | `data` | Provision | object | Cabinet credentials | | `data.keyUserId` | Provision | non-empty string | Cabinet user ID | | `data.password` | Provision | non-empty string | Visitor cabinet PIN or password | | `unreturnedKeyIds` | Check-return | array of strings | Top-level list of outstanding requested key IDs; may be empty | A successful Keys response is a complete inventory snapshot. Missing keys can be removed from Sine; never return a partial or empty success when retrieval failed. ## Lifecycle and Timing | Stage | Behaviour | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Inventory | Sine imports keys into a dynamic asset type; sync is scheduled daily and can be triggered by saving active configuration or by an operator | | Provision | Sine requests a user during pass creation; access remains inactive | | Activate | Sine requests access after check-in or acceptance | | Credential delivery | Sine attempts email after successful activation when an email address is available | | Rejection | Sine requests immediate deprovision | | Check-out | Sine checks return status and requests deprovision after the grace period | | Grace period | At least 15 minutes after check-out before the follow-up check and deprovision attempt; outstanding keys or a failed return check do not prevent the attempt | Provisioned users must not have the requested key access until Activate. Check-return does not mark Sine asset assignments as returned, and Deprovision does not confirm physical key return. ## Error Handling Return a non-success HTTP status and a safe JSON error when an operation fails. For example: ```json { "code": "REQUEST_FAILED_ERROR", "message": "Unable to complete the requested operation." } ``` Suggested statuses include `400` for invalid input, `401` for invalid credentials, `403` for forbidden access and `409` for a conflict. ## Glossary | Term | Definition | | ------------------- | ------------------------------------------------------------------------------- | | KMI | Key Management Integration framework | | KMS | Key management system controlling the cabinet | | Integration service | Your externally hosted implementation of the KMI endpoints | | Dynamic asset type | Sine's integration-managed list of key options | | `externalId` | Customer-specific configuration identifier | | Key group | Cabinet-defined inventory selection group or equivalent | | Key reference | Key ID returned by your service and used in Sine's form selections | | Cabinet credentials | Visitor user ID and PIN or password returned by Provision | | KMI API key | Secret Sine sends to authenticate to your service | | Grace period | Delay after check-out before the follow-up return check and deprovision attempt |