Getting started

What the API is for

The SnapKey Public API lets your own systems drive access control in SnapKey without anyone opening the dashboard. It carries two flows.

Your system → SnapKey. Your HR or facility system creates and updates the people who need access, and issues keys to them. Issuing a key sends the person a setup link (SMS or e-mail); the key issued this way appears once they activate that link. GET /keys also lists keys that never had a setup link — physical cards and iLOQ S5 fobs managed elsewhere — so read type to tell them apart.

SnapKey → your system. Read the access events from the doors (GET /events), or subscribe to webhooks and have SnapKey push each event to a URL you control.

Everything you can read or write is limited to the location your API key belongs to and the departments underneath it.

Get an API key

API keys are created in the SnapKey dashboard under Developer → API keys. The full token is shown once, at creation — store it in your secret manager; SnapKey keeps only a hash and the sk_live_9f3c prefix.

Every key carries an expiry date: 1 year by default, up to 2 years if the person creating it sets one further out. There is no non-expiring key.

The scopes a key holds are chosen when it is created. A request to an endpoint whose scope the key does not hold answers 403 insufficient_scope.

Your first call

GET /locks lists the doors your key can see, and needs only the catalog:read scope — a good way to prove the token works.

curl -X GET "https://api.snapkey.dk/public/v1/locks" \
  -H "Authorization: Bearer $SNAPKEY_API_KEY"

{
  "data": [
    {
      "id": 4172,
      "name": "Main entrance",
      "serial_number": "S5-004172",
      "place": "Ground floor, east",
      "provider": "iloq",
      "online": null,
      "security_groups": [
        "HQ-STAFF"
      ],
      "location": {
        "id": 12,
        "name": "Headquarters"
      }
    }
  ],
  "next_cursor": null
}

Paging through a list

Every list endpoint returns a cursor page:

{ "data": [ … ], "next_cursor": "eyJpZCI6NDE3MiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ" }

• limit — items per page, 1–200, default 50. Values outside the range are clamped.
• cursor — opaque; pass back the next_cursor of the previous page verbatim.

next_cursor is null on the last page. Rows are ordered by id ascending, so a page never reshuffles under you while you walk it.

curl -X GET "https://api.snapkey.dk/public/v1/events?since=2026-09-01T00%3A00%3A00Z&lock_id=4172&person_id=9c1f2a84-3b7e-4d21-9f60-5a2c8d7e1b40&type=access.granted%2Caccess.denied" \
  -H "Authorization: Bearer $SNAPKEY_API_KEY"

Walking every page means repeating the same request with the next_cursor you were just handed, until next_cursor comes back null:

GET /public/v1/events?limit=50
GET /public/v1/events?limit=50&cursor=<next_cursor from the previous page>

Send SnapKey a person and issue a key

First create the person. POST /people is idempotent on phone and e-mail: if a person in the API key's scope already has the same normalised phone number or the same e-mail address, that person is returned with 200 OK and nothing is changed. A genuinely new person answers 201 Created.

curl -X POST "https://api.snapkey.dk/public/v1/people" \
  -H "Authorization: Bearer $SNAPKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Mette Sørensen", "email": "mette.sorensen@example.com", "phone": "+4520123456", "company_name": "Tidevand Energi", "title": "Facility Manager", "language": "da", "location_id": 12 }'

{
  "id": "9c1f2a84-3b7e-4d21-9f60-5a2c8d7e1b40",
  "name": "Mette Sørensen",
  "email": "mette.sorensen@example.com",
  "phone": "+4520123456",
  "company_name": "Tidevand Energi",
  "title": "Facility Manager",
  "language": "da",
  "location": {
    "id": 12,
    "name": "Headquarters"
  }
}

Then issue the key with the person's id. SnapKey creates an invitation and sends the person a setup link over SMS, e-mail or both; the call answers 202 Accepted with the invitation, not a key.

curl -X POST "https://api.snapkey.dk/public/v1/keys" \
  -H "Authorization: Bearer $SNAPKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "person_id": "9c1f2a84-3b7e-4d21-9f60-5a2c8d7e1b40", "security_groups": [ "HQ-STAFF" ], "name": "Headquarters staff", "starts_at": "2026-09-01T00:00:00Z", "expires_at": "2027-09-01T00:00:00Z", "channel": "sms" }'

The key itself appears in GET /keys with state handed_over once the person activates the setup link, and fires the key.activated webhook at that moment.

Manage a key after issuing it

The invitation_id from POST /keys is a resource of its own. Read it to see whether the person has activated the link yet:

curl -X GET "https://api.snapkey.dk/public/v1/invitations/<id>" \
  -H "Authorization: Bearer $SNAPKEY_API_KEY"

{
  "id": 5521,
  "state": "activated",
  "person_id": "9c1f2a84-3b7e-4d21-9f60-5a2c8d7e1b40",
  "key_id": 88213,
  "name": "Headquarters staff",
  "security_groups": [
    "HQ-STAFF"
  ],
  "starts_at": "2026-09-01T00:00:00Z",
  "expires_at": "2027-09-01T00:00:00Z",
  "sent": {
    "email_at": null,
    "sms_at": "2026-09-19T08:12:03Z"
  },
  "created_at": "2026-09-19T08:12:02Z"
}

state moves from pending to activated when the person turns the link into a key; key_id then names that key. If the message never reached them, send it again — over SMS, e-mail or both:

curl -X POST "https://api.snapkey.dk/public/v1/invitations/<id>/resend" \
  -H "Authorization: Bearer $SNAPKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "both" }'

A link sent to the wrong person is recalled with DELETE /invitations/{id}; it cannot be activated afterwards. Both calls work on pending invitations only and answer 409 invitation_not_pending otherwise.

Once the key exists, change its security groups or validity window in place:

curl -X PATCH "https://api.snapkey.dk/public/v1/keys/<id>" \
  -H "Authorization: Bearer $SNAPKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "security_groups": [ "HQ-STAFF", "HQ-PARKING" ], "expires_at": "2027-09-01T00:00:00Z" }'

{
  "id": 88213,
  "name": "Headquarters staff",
  "type": "digital",
  "state": "sent",
  "person_id": "9c1f2a84-3b7e-4d21-9f60-5a2c8d7e1b40",
  "invitation_id": 5521,
  "security_groups": [
    "HQ-STAFF",
    "HQ-PARKING"
  ],
  "starts_at": "2026-09-01T00:00:00Z",
  "expires_at": "2027-09-01T00:00:00Z"
}

Any change other than a rename puts the key back into state sent until the locking system confirms it, and key.activated fires again at that moment. Revoking is still DELETE /keys/{id}.

Live status and remote unlock

A lock SnapKey opens over the network reports whether its device is reachable:

curl -X GET "https://api.snapkey.dk/public/v1/locks/<id>" \
  -H "Authorization: Bearer $SNAPKEY_API_KEY"

{
  "id": 4172,
  "name": "Main entrance",
  "serial_number": null,
  "place": "Ground floor, east",
  "provider": "teltonika",
  "online": true,
  "security_groups": [
    "HQ-STAFF"
  ],
  "location": {
    "id": 12,
    "name": "Headquarters"
  }
}

online is null for an iLOQ lock — SnapKey cannot see a cylinder. To open a remote lock your API key needs the locks:control scope and the lock on its allowlist, chosen when the key is created in the dashboard. The call answers 202 with a command; the door is not open yet.

curl -X POST "https://api.snapkey.dk/public/v1/locks/<id>/unlock" \
  -H "Authorization: Bearer $SNAPKEY_API_KEY"

{
  "id": "0d3f6c2a-7b1e-4f0a-9c8d-2e5b7a1f4c33",
  "lock_id": 4172,
  "status": "published",
  "requested_at": "2026-09-19T09:40:11Z",
  "published_at": "2026-09-19T09:40:11Z",
  "confirmed_at": null,
  "timeout_seconds": 10,
  "error": null
}

Poll the command, or wait for access.granted (the device confirmed) or unlock.failed (it did not) on your webhook. A lock outside the key's allowlist answers 403 lock_not_allowed and is logged as a refused access, so the attempt shows up in GET /events like any other.

Get live feedback

Subscribe a URL to the door and key events and SnapKey pushes each one to you as it is recorded — see Webhooks for the payloads, the signature check and the retry ladder.

GET /events serves the same door events as a list: poll it, and replay from it with since= after a webhook gap.

Tools

Import the OpenAPI file into Postman or Insomnia:

https://api.snapkey.dk/docs/openapi.json

Prefer a document? Download the full documentation as PDF from the box below.