--- title: Getting Started slug: frameworks/kmi-getting-started createdAt: 2026-11-03T06:49:31.466Z --- # Introduction ## Purpose of This Document This guide describes **version 1.0** of Sine's **Key Management Integration (KMI) framework**. It explains how to build and host an integration that connects a key management system (KMS) or key cabinet to Sine. You build and host an integration service that implements the KMI endpoints. A Sine administrator configures the endpoint addresses and an API key in Sine. Sine then calls your service during key synchronisation and the visitor lifecycle; your service translates those calls to the cabinet's API. The KMI specification defines a standard interface for connecting a compatible integration without bespoke Sine development. ## Who This Document Is For These guides are for developers building an integration between Sine and a key cabinet. You should be familiar with HTTPS APIs, JSON, authentication and the cabinet's user, key-permission and key-return model. Start with this page for the architecture and lifecycle. Use the [Implementation Guide](docId\:Yhwc63UQsxJo8sMgylSvB) for request and response examples, and [Testing & Deployment](docId:0qzYmaRWBtjgCOTMg3QAF) to prepare your service for integration. No prior knowledge of Sine's architecture is required. Sine-specific terms are explained in [Core Concepts and Terminology](docId\:nU3QcpZMjH8LsZjqklZEL). ## What KMI Enables Your service implements seven operations: 1. [Verify endpoint](docId\:Yhwc63UQsxJo8sMgylSvB) - validate the connection. 2. [Resources endpoint](docId\:Yhwc63UQsxJo8sMgylSvB) - list key groups available for selection. 3. [Keys endpoint](docId\:Yhwc63UQsxJo8sMgylSvB) - return the keys in the selected groups. 4. [Provision endpoint](docId\:Yhwc63UQsxJo8sMgylSvB) - create or prepare a cabinet user for a visitor. 5. [Activate endpoint](docId\:Yhwc63UQsxJo8sMgylSvB) - grant the visitor access to the requested keys. 6. [Check-return endpoint](docId\:Yhwc63UQsxJo8sMgylSvB) - report which requested keys are outstanding. 7. [Deprovision endpoint](docId\:Yhwc63UQsxJo8sMgylSvB) - remove the visitor's cabinet access. Your service is responsible for connecting to the cabinet API, mapping identifiers and maintaining any cabinet-specific configuration. Sine manages visitor passes, key selections and the lifecycle calls described in this specification. ## Scope and Limitations KMI covers key inventory retrieval, visitor cabinet access and key-return status. It does not define the cabinet vendor's API or how your service implements vendor-specific operations. The following are outside the KMI contract: - General asset-management integrations for items other than keys. - Door access credentials, badges and reader operations. - Physical key recovery or cabinet maintenance. - Cabinet-specific user interfaces and administrative procedures. Check-return reports custody information; it does not mark Sine asset assignments as returned. Deprovision removes cabinet access; it does not confirm that physical keys have been returned. ## Prerequisites - Access to a non-production key cabinet and its API documentation. - Cabinet API credentials with the permissions needed to read keys and manage users and access. - A service that can receive HTTPS requests from Sine and call the cabinet API. - A secure way to store the cabinet API credentials and the KMI API key. - Test key groups, keys and synthetic visitor details. - A Sine test site for integration testing. Do not include real credentials, visitor PINs or personal data in shared examples or test fixtures. # Architecture Overview ## System Context | Component | Responsibility | | ------------------------ | ------------------------------------------------------------------------------- | | Sine | Provide the visitor workflow, synchronise key options and call your endpoints | | Your integration service | Authenticate Sine requests, implement the KMI contract and call the cabinet API | | Key management system | Manage key inventory, cabinet users, permissions and custody records | | Key cabinet | Allow authorised users to collect and return physical keys | ```mermaid flowchart LR visitor["Visitor"] sine["Sine"] integration["Your integration service"] kms["Key management system"] cabinet["Key cabinet"] visitor -->|"Select keys / check in and out"| sine sine -->|"HTTPS KMI requests"| integration integration -->|"Cabinet API requests"| kms kms -->|"Inventory and custody data"| integration integration -->|"KMI responses"| sine kms -->|"Users and key permissions"| cabinet visitor -->|"Credentials / physical key return"| cabinet ``` Your service owns the cabinet connection and its credentials. The KMI API key authenticates Sine to your service; it is not the visitor's cabinet PIN. ## Responsibilities Summary | Responsibility | Sine | Your integration | | -------------------------------------------------------------- | ---- | ---------------- | | Manage visitor passes and determine lifecycle triggers | Yes | | | Select key groups and present synchronised key options | Yes | | | Call the configured KMI endpoints | Yes | | | Authenticate requests and authorise the customer configuration | | Yes | | Retrieve complete cabinet inventory and maintain stable IDs | | Yes | | Translate KMI operations into cabinet API calls | | Yes | | Keep requested key access inactive until Activate | | Yes | | Return cabinet user credentials and custody results | | Yes | | Attempt visitor credential emails and return reminders | Yes | | | Remove cabinet access when Deprovision is received | | Yes | | Handle duplicate requests and uncertain cabinet writes safely | | Yes | ## Connecting Sine to Your Service KMI uses an HTTPS URL for each operation, along with a customer-specific `externalId` and a dedicated API key authorised for that identifier. The URLs can point to different paths on the same service. Sine sends a `POST` request with JSON and the configured API key in the `Authorization` header. Your service validates the key, processes the request and returns the specified JSON response. See the [Implementation Guide](docId\:Yhwc63UQsxJo8sMgylSvB) for the headers, payloads and endpoint behaviour. # Lifecycle Overview ## 1. Synchronise Key Inventory Sine calls your [Resources endpoint](docId\:Yhwc63UQsxJo8sMgylSvB) to let an administrator choose the key groups to import. It then calls your [Keys endpoint](docId\:Yhwc63UQsxJo8sMgylSvB) with the selected group IDs. Your service returns the complete set of matching cabinet keys. Sine uses the response to populate a dynamic asset type - an integration-managed list of key options that can be used in a check-in form. The key IDs returned by your service are retained as references and sent back when a visitor selects keys. Inventory flows **from the cabinet system to Sine**. A successful response represents the inventory to reconcile: a key missing from that response may be removed from Sine. If your cabinet API is unavailable or returns only part of its inventory, return an error rather than an empty or partial success. Key inventory synchronisation is scheduled daily and can also be triggered when active configuration is saved or by an operator. ## 2. Provision and Activate Access ```mermaid sequenceDiagram autonumber participant V as Visitor participant S as Sine participant I as Your integration service participant K as Key management system V->>S: Check in and request keys S->>I: Provision visitor and requested keys I->>K: Create or prepare cabinet user I-->>S: PROVISIONED with user ID and password S->>S: Complete any required approval S->>I: Activate user and requested keys I->>K: Enable the requested permissions I-->>S: ACTIVATED opt Visitor email available S-->>V: Send cabinet credentials end ``` Provisioning and activation are separate operations. Your [Provision endpoint](docId\:Yhwc63UQsxJo8sMgylSvB) prepares the cabinet user without granting access to the requested keys. Your [Activate endpoint](docId\:Yhwc63UQsxJo8sMgylSvB) grants access when Sine calls it after check-in or approval. 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`. These credentials are response fields returned to Sine, not fields Sine supplies in the request. Sine uses the returned user ID to correlate later requests and may email the returned credentials to the visitor after activation. Sine waits for the Provision endpoint's response during pass creation, so a slow response can delay check-in. A cabinet failure handled by Sine does not, by itself, reject check-in. Activation or email failure does not roll back an already completed check-in. A completed check-in is therefore not proof that cabinet access is available. ## 3. Check Return and Remove Access ```mermaid sequenceDiagram autonumber participant V as Visitor participant S as Sine participant I as Your integration service participant K as Key management system V->>S: Check out S->>I: Check-return for requested keys I->>K: Read key custody state I-->>S: Outstanding key IDs opt Outstanding keys and visitor email available S-->>V: Return reminder end S->>S: Wait for return grace period S->>I: Check-return again S->>I: Deprovision I->>K: Remove the visitor's cabinet access I-->>S: DEPROVISIONED ``` Your [Check-return endpoint](#) reports the requested key IDs that are still outstanding, using the cabinet's custody information. Do not report an unknown status as a confirmed return. After check-out, Sine waits at least 15 minutes before attempting the follow-up return check and deprovision. This grace period applies even if the first return check fails or reports no outstanding keys. Sine attempts deprovision even if the follow-up check fails or keys remain outstanding. Outstanding keys do not automatically extend access. Check-return informs Sine activity and reminders; it does not itself mark Sine asset assignments as returned. If a provisioned pass is rejected, Sine calls your [Deprovision endpoint](docId\:Yhwc63UQsxJo8sMgylSvB) without the check-out grace period. # Core Concepts and Terminology ## Lifecycle States | State | Meaning | | ------------- | --------------------------------------------------------------------------------------------- | | Provisioned | A cabinet user and credentials are available, but the requested key access is not yet enabled | | Activated | The cabinet user has access to the requested keys | | Deprovisioned | The visit's cabinet access has been removed or disabled | Cabinet access and physical custody are separate: a deprovisioned user can still have outstanding keys. ## Identifiers and Validity Treat customer, group, key and user identifiers as strings, preserving leading zeroes. Key IDs returned by Keys are the values sent back in `requestedKeyIds`; they are not Sine asset IDs. Provision supplies `visitId`, `validFrom`, `validTo` and `timezone`. Store the visit-to-user association and the validity information needed by your cabinet. Activate, Check-return and Deprovision identify the cabinet user through `keyUserId`; they do not repeat `visitId` or the validity fields. ## Glossary | Term | Meaning | | ------------------- | --------------------------------------------------------------------------------------------- | | KMI | Key Management Integration framework | | KMS | Key management system that controls the cabinet and its records | | Integration service | Your externally hosted implementation of the KMI endpoints | | `externalId` | Customer-specific identifier used by your service to select the correct cabinet configuration | | Key group | A cabinet-defined group, or an equivalent grouping exposed by your service | | Dynamic asset type | Sine's integration-managed list of key options | | `visitId` | Sine's identifier for the visitor pass | | `keyUserId` | Cabinet-side user identifier returned by Provision | | `requestedKeyIds` | Key identifiers returned by your service and selected by the visitor | | `unreturnedKeyIds` | Requested key identifiers your service reports as outstanding | | Cabinet password | The visitor's cabinet PIN or password, distinct from the KMI API key |