Skip to content

Sharing

Note

We're sorry, this article hasn't been completed or updated yet. We're working on finishing it as soon as possible. In case of any questions, please reach out to our Support Team.

Shared venues and devices

In V6.0 of the REST API we introduced the concept of shared venues and shared devices.

Sharing allows you to give access to your Venues and Devices to other managers without having to share your API key.

You can share Venues complete with all their Devices and Actions with one or more managers outside of your company. You can also share Venues publicly.

You can share individual devices and allow users to add them to their own venues.

To initiate a share, you need to specify the email address of the managers you want to share with. To share publicly, you simply share with the public manager public-infrastructure@kontakt.io.

Only the manager who 'owns' the Venue or Device can initiate a share.

Any shares will be visible to your supervisor managers. Public shares are visible to anyone using the public api-key.

{% note|warning %} It is highly recommended to change proximity UUID of Your beacons before You share them {% endnote %}

Access

You can share in one of two ways.

VIEWER - The managers you share with have only read access to the shared venues or devices and their actions. This is the only option available if you are sharing publicly.

EDITOR - this option only applies to devices (not venues). If a device is shared with you exclusively, then a copy of the device is created. No actions from the original device will be added to the copy, and its original venue relationship will not be copied. You can add your own actions to the copy and assign the copy to one of your venues. Your actions and venues will not be visible to to the device owner or other shares. You cannot update devices or create configs for devices that have been shared with you exclusively.

Sharing publicly

A public Venue can be accessed by anyone using our PUBLIC api key, and all Devices and Actions assigned to the public Venue will also be publicly available.

If you share one of your venues with the public manager public-infrastructure@kontakt.io, this venue becomes available to any managers accessing the API with the Kontakt.io public api-key:

YVMS1AZhgAEjC1Krg5X5tiI9AhhmpgbP

Public venues can only be shared as VIEWER i.e. in read-only mode.

Accessing public Venues

You can access any venue that has been shared publicly and its devices and actions. You just need to use the public api-key key in place of your own manager api-key to access the api.

Getting devices or venues using the public api-key will only return public venues and devices.

You can use the following resources to retrieve information about public venues, devices and actions.

Notifications

Once you share a venue/device with a manager or managers, they will receive an email containing information for the shared device.

If an expiration date is set for the share, the manager you have shared the venue/device with will receive an warning email before the share expires.

Expiry

When you share a Venue or Device, by default it will be shared forever or until you delete or unshare it. You have the option to specify an expiry date when you create the share. The device or venue will be 'unshared' when the date is reached. The expiry date is a timestamp e.g. 1429610639 this is compared with the current time (UTC).

Share type

We have added two new fields to devices and venues: access and shares. access details your relationship with the device or venue. Access can have one of the following values:

  • OWNER This venue/device belongs to you
  • SUPERVISOR This venue/device belongs to a subordinate manager of yours
  • VIEWER This venue/device has been shared with you in read-only mode.
  • EDITOR This device has been shared with you in exclusive mode.

If you have shared one of your venues or devices, a new entry will be added to the shares for your venue/device.

shares records the details for each share you have made:

  • email of the manager you have shared with
  • expiry date of the share
  • share type - VIEWER or EDITOR

Unsharing

The owner of a shared device can withdraw the share at any time. If you withdraw a device that was shared EDITOR then all changes to this device copy will be lost.

Updating shared venue expiry

Currently shared venue expiry cannot be updated. This means that once an expiration date has been set for the share, it cannot be extended and the share will expire once the date is reached.