API og Webhook-integrationer – Automatiser din adgangskontrol med SnapKey

SnapKey tilbyder et REST API og webhooks for at integrere adgangskontrol med jeres eksisterende systemer. Denne guide er skrevet til udviklere og IT-arkitekter der vil automatisere adgangsstyring.

---

Integration-muligheder

---

REST API Overview

SnapKey Public API er et REST API på https://api.snapkey.dk/public/v1. Det bærer to flows:

• Jeres system → SnapKey: opret og opdatér personer, og udsted, ret og tilbagekald nøgler.
• SnapKey → jeres system: hent dørenes hændelser med GET /events, eller få dem skubbet til jer som webhooks.

Denne side er et overblik. Den fulde reference med alle endpoints, requests og svar findes i SnapKeys udviklerdokumentation (på engelsk).

Authentication

Hvert kald bærer et bearer-token:

Authorization: Bearer sk_live_…

API-nøgler oprettes i SnapKey-dashboardet under Developer → API keys. Det fulde token vises én gang, når nøglen oprettes. Hver nøgle har en eksplicit liste af scopes og udløber som standard efter et år (højst to). En nøgle ser kun sin egen lokation og afdelingerne under den. Se Authentication & limits.

Hvad API'et dækker

Scope	Giver adgang til
catalog:read	GET /locks, GET /locks/{id}, GET /security_groups
people:read / people:write	/people
keys:read / keys:write	/keys og /invitations
locks:control	POST /locks/{id}/unlock – kun fjernstyrede låse på API-nøglens tilladelsesliste
events:read	GET /events
webhooks:manage	/webhooks

Når en nøgle udstedes med POST /keys, får personen et opsætningslink på SMS, e-mail eller begge. Nøglen dukker op i GET /keys, når linket er aktiveret. Se Getting started.

OpenAPI-filen til Postman eller Insomnia ligger på https://api.snapkey.dk/docs/openapi.json.

---

Webhooks

Opret et abonnement med POST /webhooks eller i dashboardet under Developer → Webhooks. URL'en skal være https:// på en offentlig vært. SnapKey genererer signeringsnøglen og returnerer den én gang.

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

Dørkontakt- og hold-hændelser (kræver en SnapGate-dørkontakt / udgangsknap):
├─ 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

Hver hændelses payload står i Webhooks.

Verificér en levering

Hver levering har en signatur-header:

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

Beregn HMAC-SHA256 over "{t}.{raw body}" med abonnementets signeringsnøgle, sammenlign med v1 i konstant tid, og afvis et t, der ligger mere end 300 sekunder fra jeres eget ur. Færdig kode til Node.js, Python, C# og PHP står i Webhooks.

Svar med en 2xx inden for 10 sekunder. En fejlet levering prøves igen efter 1 m, 5 m, 30 m, 2 t, 6 t og 24 t. Levering sker mindst én gang og uden fast rækkefølge, så fjern dubletter på data.id sammen med type.

---

Typiske integrationer

• HR-system: opret personen og udsted nøgler ved ansættelse; tilbagekald med DELETE /keys/{id} ved fratrædelse.
• Entreprenører: udsted en nøgle med et gyldighedsvindue; personen får et opsætningslink på SMS eller e-mail.
• Sikkerhedsovervågning: abonnér på access.denied og unlock.failed, og hent historikken fra GET /events efter et hul.
• Bygnings- og besøgssystemer: reagér på access.granted i jeres eget system.

---

Rate Limits

600 kald i minuttet pr. API-nøgle. POST /keys er begrænset til 30 i minuttet, fordi hvert kald sender en SMS eller e-mail. Overskrides en grænse, svarer API'et 429 med en Retry-After-header. POST /people, POST /keys og POST /webhooks tager imod en Idempotency-Key-header, så et nyt forsøg efter en timeout ikke skaber en dublet. Se Authentication & limits.

---

FAQ

---

Kontakt os

Brug for hjælp til at komme i gang med SnapKey API? Vores udviklerteam står klar.