Skip to main content

Send access links

By sending an access link, you can allow one-time users, visitors, and temporary staff to unlock doors in your place without having to sign up for a Kisi account or download the mobile apps. Depending on your needs, you can either:

  1. Send access links via automated emails
  2. Send access links via customized emails
  3. Fetch doors to create custom landing pages
info

Users with an access link can unlock doors associated with the link without having to authenticate themselves. Therefore, we recommend using this feature only for temporary access and for low-security doors.

In this use case, once you run the request, Kisi will send an automatic email to the defined email address, containing the access link. Once clicking on the link, the user will land on a Kisi-branded page with one or more doors they are provided access to.

  1. Send a POST request to the Create group link endpoint, following the example below.

Example

curl --request POST \
  --url https://api.kisi.io/group_links \
  --header 'Authorization: KISI-LOGIN <API_KEY>  ' \
  --header 'Content-Type: application/json' \
  --data '{
  "group_link": {
    "name": "string",
    "group_id": 0,
    "email": "user@example.com",
    "valid_from": "2019-08-24T14:15:22Z",
    "valid_until": "2019-08-25T14:15:22Z"
  }
}'
  • name - the name of the access link
  • group_id - the ID of the group the access link will be associated to
  • email - the email address the access link will be sent to
  • valid_from - the date and time at which the access link becomes valid
  • valid_until - the date and time at which the access link ceases to be valid
tip

Make sure to provide a meaningful name (e.g. the name of the user to whom the access link is sent to) to simplify access and unlock events auditing.

Response

If your request was successful, you'll receive a 200 OK response with the access link object, the user by whom it has been issued, and the authentication token associated with this access link.

{
  "id": 0,
  "email": "user@example.com",
  "group_id": 0,
  "name": "string",
  "valid_from": "2019-08-24T14:15:22Z",
  "valid_until": "2019-08-25T14:15:22Z"
  "issued_by": {
    "id": 0,
    "name": "string",
    "email": "user@example.com"
  },
  "secret": "0"
}
info

An access link is always associated to a group. This means, the link provides access to the same doors its associated group provides access to.

In some cases, you might want to omit the automatic Kisi email and customize it yourself before sending the access link.

  1. Send a POST request to the Create group link endpoint, while omitting the email field

Example

curl --request POST \
  --url https://api.kisi.io/group_links \
  --header 'Authorization: KISI-LOGIN <API_KEY>  ' \
  --header 'Content-Type: application/json' \
  --data '{
  "group_link": {
    "name": "string",
    "group_id": 0,
    "valid_from": "2019-08-24T14:15:22Z",
    "valid_until": "2019-08-25T14:15:22Z"
  }
}'
  1. Copy the secret value that is returned upon link creation
  2. Paste the secret value to the end of https://web.kisi.io/grouplinks/ when composing your email

Example

https://web.kisi.io/grouplinks/123

Fetch doors to create custom landing pages​

On top of customizing emails, you might also want to design a custom page that presents the available doors to the user, e.g. add your own logo, colors, or render the door buttons based on your company's design guidelines.

To achieve this, you can fetch a list of all doors that the link provides access to, and use this information to create your own custom doors overview page.

  1. Generate the access link as shown in the previous step
  2. Copy the secret value that is returned upon link creation
  3. In a new request, change the Authorization header value to KISI-GROUP-LINK
  4. Paste the secret value right after KISI-GROUP-LINK
  5. Send a GET request to the Fetch locks endpoint, as shown below

Example

curl --request GET \
  --url https://api.kisi.io/locks \
  --header 'Authorization: KISI-GROUP-LINK <secret>  ' \
  --header 'Content-Type: application/json'

Response

If your request was successful, you'll receive a 200 OK response with a list of doors that the respective link provides access to.