Quick Reference

10 min

KMI Reference

Implement seven HTTPS endpoints in your integration service. Once the generic framework is available, a Sine administrator would configure the endpoint URLs, KMI API key, customer externalId and selected key groups.

Operation Summary

Operation	Sine lifecycle trigger	Proposed 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	Sign-out and delayed return check	200, code: "SUCCESS" and top-level unreturnedKeyIds
Deprovision	Pass rejection or delayed sign-out task	200, code: "DEPROVISIONED"

All seven operations use POST with JSON in the proposed contract. The endpoint URLs are configured separately; example paths in these guides are illustrative.

Authentication

Authorization: <REPLACE_ME>
Content-Type: application/json
Accept: application/json

The proposed Authorization value is the KMI API key configured in Sine. The framework would send 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.

Common Request Fields

Field	Proposed requirement	Purpose
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 existing Sine asset identifier limit is 100 UTF-16 code units including its type prefix, :: separator and key ID; overlong key IDs are skipped. Confirm this constraint for the generic framework.

Provision Request

Field	Proposed value
visitId	Sine pass ID
visitor.firstName, visitor.lastName	Required non-empty visitor name strings
visitor.email, visitor.mobile	Optional contact strings; at least one must be non-empty
validFrom, validTo	Visit validity as ISO UTC timestamps
timezone	Site timezone
requestedKeyIds	Non-empty array of non-empty key ID strings returned by your service

Provision returns data.keyUserId and data.password. Both are required non-empty strings in the proposed contract. The password is a visitor cabinet credential, not the KMI API key.

Post-Provision Requests

Activate, Check-return and Deprovision receive:

Field	Proposed value
config.externalId	Customer or cabinet configuration identifier
config.keyGroupIds	Selected groups, when supplied
keyUserId	Required non-empty cabinet user ID returned by Provision
requestedKeyIds	Required array of non-empty key ID strings recorded for the visit

Activate requires a non-empty requestedKeyIds array. Check-return and Deprovision accept an empty array. 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.

These operations do not include visitId. Store the externalId/visitId to keyUserId association during Provision and use the customer and user ID to resolve later requests.

Response Fields

Field	Operation	Meaning
keyGroups[].id, keyGroups[].name	Resources	Stable group ID and display name
data[].id, data[].name	Keys	Stable key ID returned by your service and display name
data.keyUserId	Provision	Cabinet user ID
data.password	Provision	Visitor cabinet PIN or password
unreturnedKeyIds	Check-return	Requested key IDs still outstanding

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	Proposed behaviour
Inventory	Sine imports keys into a dynamic asset type; daily, save-triggered and operator-initiated sync are proposed
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
Sign-out	Sine checks return status and schedules delayed deprovision
Grace period	Proposed 15-minute delay; outstanding keys or a failed return check do not automatically prevent deprovision

The proposed lifecycle is extrapolated from an existing integration. Generic endpoint availability, grace timing, timeouts, retries and delivery guarantees must be confirmed before release.

Error Handling

Return a non-success HTTP status and a safe JSON error when an operation fails. The proposed error shape is:

{
  "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. The final error catalogue remains to be agreed.

Glossary

Term	Definition
KMI	Proposed 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	Proposed delay after sign-out before deprovision

See the Implementation Guide for payload examples, Testing & Deployment for the proposed setup, and Troubleshooting for recovery guidance.