Quick Reference
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
Authorization: <REPLACE_ME>
Content-Type: application/json
Accept: application/jsonThe 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:
{
"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 |