API and Webhook Integrations – Automate Your Access Control with SnapKey

SnapKey offers a REST API and webhooks to integrate access control with your existing systems. This guide is written for developers and IT architects who want to automate access management.

---

Integration Options

---

REST API Overview

The SnapKey Public API is a REST API at https://api.snapkey.dk/public/v1. It carries two flows:

• Your system → SnapKey: create and update people, and issue, change and revoke keys.
• SnapKey → your system: read the door events with GET /events, or have them pushed to you as webhooks.

This page is an overview. The full reference, with every endpoint, request and response, is in the SnapKey developer documentation.

Authentication

Every request carries a bearer token:

Authorization: Bearer sk_live_…

API keys are created in the SnapKey dashboard under Developer → API keys. The full token is shown once, at creation. Each key carries an explicit list of scopes and expires after one year by default (at most two). A key only sees its own location and the departments below it. See Authentication & limits.

What the API covers

Scope	Gives access to
catalog:read	GET /locks, GET /locks/{id}, GET /security_groups
people:read / people:write	/people
keys:read / keys:write	/keys and /invitations
locks:control	POST /locks/{id}/unlock – remote locks on the API key's allowlist only
events:read	GET /events
webhooks:manage	/webhooks

Issuing a key with POST /keys sends the person a setup link by SMS, e-mail or both. The key appears in GET /keys once they activate the link. See Getting started.

The OpenAPI file for Postman or Insomnia is at https://api.snapkey.dk/docs/openapi.json.

---

Webhooks

Create a subscription with POST /webhooks, or in the dashboard under Developer → Webhooks. The URL must be https:// on a public host. SnapKey generates the signing secret and returns it once.

Available Events

Access & Door Events:
├─ access.granted           # A door was opened
├─ access.denied            # A door refused a key
├─ door.closed              # A door was closed
├─ door.left_open           # Door not confirmed closed
└─ unlock.failed            # A remote unlock was never confirmed

Key Events:
├─ key.issued               # Key invitation sent
├─ key.activated            # Key activated
└─ key.revoked              # Key returned or deleted

Lock Events:
├─ lock.online              # Remote lock became reachable
└─ lock.offline             # Remote lock stopped being reachable

Door Contact & Hold Events (requires a SnapGate door contact / exit button):
├─ door.opened              # Door contact reported open
├─ door.forced              # Opened with no exit press or unlock
├─ door.exit_button         # Exit button pressed (input 2)
├─ lock.hold_open.started   # Hold relay switched on
├─ lock.hold_open.ended     # Hold relay switched off
└─ lock.hold_open.failed    # Hold could not be written or verified

Person Events:
├─ person.created           # Person created
├─ person.updated           # Person details changed
└─ person.deleted           # Person deleted

The payload of each event is in Webhooks.

Verifying a delivery

Each delivery carries a signature header:

X-SnapKey-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "{t}.{raw body}")>

Compute HMAC-SHA256 over "{t}.{raw body}" with your subscription secret, compare it with v1 in constant time, and reject a t more than 300 seconds from your own clock. Ready-made code for Node.js, Python, C# and PHP is in Webhooks.

Answer with a 2xx within 10 seconds. A failed delivery is retried after 1 m, 5 m, 30 m, 2 h, 6 h and 24 h. Delivery is at-least-once and unordered, so dedupe on data.id together with type.

---

Typical integrations

• HR system: create the person and issue keys when someone starts; revoke with DELETE /keys/{id} when they leave.
• Contractors: issue a key with a validity window; the person gets a setup link by SMS or e-mail.
• Security monitoring: subscribe to access.denied and unlock.failed, and replay history from GET /events after a gap.
• Building and visitor systems: react to access.granted in your own system.

---

Rate Limits

600 requests per minute per API key. POST /keys is limited to 30 per minute, because every call sends an SMS or e-mail. Exceeding a limit answers 429 with a Retry-After header. POST /people, POST /keys and POST /webhooks accept an Idempotency-Key header, so a retry after a timeout does not create a duplicate. See Authentication & limits.

---

FAQ

---

Contact Us

Need help getting started with the SnapKey API? Our developer team is ready to help.