Access Keys

Access keys are key/secret pairs used to authenticate device connections in the Losant platform, either against the Losant MQTT Broker or a subset of device-specific API endpoints.

Viewing Access Keys

You can view your access keys for an application by choosing "Access Keys" in the Application menu bar. The list includes each key's name (if set), key, description, and status (active/inactive), as well as a summary of restrictions placed on the key. You can click on any access key to view more details about it.

Access keys support advanced queries for filtering the list of keys by several properties, including its name, associated device IDs, topic restrictions, and more. See the Access Keys advanced query schema for more information.

Creating an Access Key

Access keys can be added to your application by using the "Add Access Key" button on the Access Keys page. The form takes several properties broken up across multiple sections, some of which may not be changed after creation.

Overview

First, provide the following optional fields:

• Name: A human-readable name for the access key. This is for your reference and has no effect on the key's functionality. (Note: Unlike most other Losant resources, this field is optional for access keys.)
• Description: A longer description for the access key.

Access keys are automatically created with a Status of "active". After creation, you may edit the access key to change its status to "inactive" if you wish to temporarily disable the key without deleting it.

Device Restrictions

Recommendation

Losant strongly recommends creating a single access key for each device, and restricting that access key to only the device it is meant to authenticate. This way, if an access key is compromised, only a single device is at risk.

Next, choose which device(s) this access key should be able to authenticate. This property cannot be changed after creating the access key.

Choose one of the following options:

• Allow all devices to connect using this access key: If selected, any device that can connect to Losant's MQTT broker will be able to authenticate using this access key.
• Allow only the following devices to connect ...: If selected, you must provide a device query that defines which devices can authenticate using this access key by specific ID and/or by tag comparison. Only devices that match the device query will be able to authenticate using this access key.

Note: Device restrictions dictate not only which devices can authenticate using this access key, but also which other devices' data can be accessed when authenticating against the Losant API with this access key. For example, if an access key is restricted to devices with the tag type=thermostat, then any device authenticated with this access key will be able to send commands and retrieve data on any other device with the tag type=thermostat – including those that cannot authenticate using this access key, such as systems and peripheral devices.

Tag Query Resolution

Device tag queries are resolved at the time of connection, which can lead to devices gaining or losing access to the MQTT broker as their tag values change. For example, given an access key with a Device Restriction of tags matching type=thermostat ...

• A device with the tag type=thermostat will be able to authenticate using this access key. However, if the tag is eventually removed from the device, or if the tag value is removed or changed to a value other than thermostat, then the device will no longer be able to authenticate using this access key.
• A device that does not have the tag type=thermostat will not be able to authenticate using this access key. However, if the tag is eventually added to the device with the value thermostat, then the device will be able to authenticate using this access key.
• If a device with the tag type=thermostat is connected to the MQTT broker using this access key, and then the tag is removed or its value is changed to something other than thermostat, the device will remain connected until it disconnects for some other reason.

Connection Restrictions

Optionally, you may restrict incoming connections using this access key to a specific set of IP addresses or CIDR blocks. If you choose to add connection restrictions, any connection attempt using this access key from an IP address that does not match one of the provided rules will be rejected.

Choose one of the following Allowed IP Addresses options:

• Allow connections from all IP addresses: (default) If selected, connections using this access key will be allowed from any IP address.
• Allow connections from ONLY these IP addresses ...: If selected, provide one or more IP addresses and/or CIDR blocks that are allowed to connect using this access key. Connections using this access key will be rejected from any IP address that does not match one of the provided rules.
• Allow connections from all EXCEPT these IP addresses ...: If selected, provide one or more IP addresses and/or CIDR blocks that are not allowed to connect using this access key. Connections using this access key will be allowed from any IP address that does not match one of the provided rules.

Security Note

Losant respects the X-Forwarded-For HTTP header when evaluating connection restrictions. If your devices connect through a proxy or gateway that sets this header, make sure that the header is set correctly and securely, as it can be easily spoofed.

Additional MQTT Topics Access

By default, access keys only allow access to the device-specific MQTT topics (e.g. state and commands) for every device matching the key's restrictions. Optionally, you can specify multiple non-device MQTT topics that devices authenticating using the key should have access to. Select one of the following Additional MQTT Topics options:

• All topics: Allow access to device-specific topics and all custom topics.
• No additional topics: (default) Allow access to only device-specific topics.
• Only the following topics...: Allow access to device-specific topics and only the listed custom topics.
• All except the following topics...: Allow access to device-specific topics and all except the listed custom topics.

If you choose "Only the following topics..." or "All except the following topics...," you will also need to provide a list of allowed/disallowed Publish Topics and a list of allowed/disallowed Subscribe Topics. Each value must be a valid MQTT topic, and furthermore, they cannot be MQTT system topics (prefixed with $SYS), or Losant-specific topics (e.g. losant/DEVICE_ID/state).

Other Methods for Creating Access Keys

In addition to generating access keys as described above, you can also create access keys through several different methods:

• From the "Other Actions" dropdown in a device's detail page - or in a device's row in the application's devices list. Keys generated here will always be scoped to a single device.
• Invoking an Access Key: Create Node in a workflow.
• Generating a key for use in the Device Simulator. Keys generated here will always be scoped to a single device.
• Using the Losant REST API's Access Keys: Post endpoint.

Access Secret

After creating an access key, the newly generated key and secret will be displayed. You will either need to copy your key and secret to a secure location or download them to a file on your computer.

Important

Losant does not store key secrets, and they cannot be recovered or regenerated if lost. If you fail to save your key secret before closing the window, you will have to generate a new access key / secret pair.

After you've saved your access key and secret, check the "I have copied my access key and secret to a safe place" box and click "Close Window".

Deleting / Deactivating an Access Key

To temporarily deactivate an access key:

• Click the switch alongside the access key in the list view, OR
• From the access key's detail page, toggle the switch from "active" to "inactive".

If an access key is no longer needed, or you believe it has been compromised, you may permanently delete it by:

• Clicking on the Delete icon in the access key list, OR
• Clicking the Delete Access Key button on the access key's detail page

Using Access Keys

To find out more about using access keys with our MQTT clients, check out the various Losant MQTT client libraries. To learn more about using access keys with our REST API, check out the various Losant REST client libraries.