Getting Started

12 min

Introduction

What Is KMI?

The Key Management Integration (KMI) framework is a proposed way for third-party developers to connect 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 goal is that, once the generic framework is available, a compatible integration can be configured without bespoke Sine development.

Who Is This 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 for request and response examples, and Testing & Deployment to prepare your service for integration.

What Your Integration Does

Your service implements seven operations:

Verify - validate the connection.

Resources - list key groups available for selection.

Keys - return the keys in the selected groups.

Provision - create or prepare a cabinet user for a visitor.

Activate - grant the visitor access to the requested keys.

Check-return - report which requested keys are outstanding.

Deprovision - 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 proposal.

What You Need

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 once the generic KMI integration is available.

Do not include real credentials, visitor PINs or personal data in shared examples or test fixtures.

Architecture

Components

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

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

In the proposed model, 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.

Connecting Sine to Your Service

The proposed setup uses an HTTPS URL for each KMI 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. Exact configuration controls, connectivity options and timeout settings still require agreement.

See the Implementation Guide for the proposed headers, payloads and endpoint behaviour.

Lifecycle Overview

1. Synchronise Key Inventory

Sine calls Resources to let an administrator choose the key groups to import. It then calls Keys 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.

The proposed lifecycle follows the existing daily scheduled sync, the sync attempted when active configuration is saved, and an operator-initiated sync. The generic setup and exact timing need confirmation.

2. Provision and Activate Access

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
    S-->>V: Attempt credential email

Provisioning and activation are separate operations. Your Provision endpoint should prepare the cabinet user without granting access to the requested keys. Activate grants access after check-in or approval.

The proposed response requires a cabinet user ID and password or PIN. The existing lifecycle uses these values to correlate later requests and send credentials to the visitor. Confirm how to handle cabinets that do not support this credential model before implementing.

The existing Sine lifecycle awaits Provision during pass creation. A handled cabinet failure is recorded rather than rejecting check-in solely because that call failed. Activation or email failure does not roll back an already completed check-in. These behaviours are proposed for the generic interface and must be confirmed before release.

3. Check Return and Remove Access

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. Define the result using your cabinet's custody information; do not report an unknown status as a confirmed return.

The proposal follows the existing Sine lifecycle: a deprovision task is scheduled after a 15-minute grace delay, including if the first return check fails or reports no outstanding keys. Sine attempts deprovision even if the later return check fails or keys remain outstanding. Outstanding keys do not automatically extend access. The delay and behaviour require confirmation for the generic framework.

Check-return informs Sine activity and reminders; it does not itself mark Sine asset assignments as returned.

Terminology

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