Access Key: Create Node

The Access Key: Create Node allows a workflow to create a new Access Key inside the current application. This key can then be used to authenticate a WEGnology Device against the platform’s MQTT broker.

Node Properties

Start by choosing how you wish to configure your new Access Key. Choose one of the following options in the “Data Method” dropdown:

• Individual Fields: Define the configuration of the new Access Key using individual string templates per property.
• Payload Path: Provide a payload path pointing to an object containing the Access Key’s full configuration. The object must validate against the new Access Key schema.
• JSON Template: Define a JSON template string that resolves to a JSON object containing the Access Key’s full configuration. The object must validate against the new Access Key schema.

When choosing the “Individual Fields” option, there are a few fields that must be configured.

Access Restrictions

Specify whether all devices may use the new Access Key to authenticate against the MQTT broker, or if only the following devices can use the Access Key (recommended). When selecting the latter option, you must also provide a device query targeting at least one device ID or device tag. The query accepts string templates for defining specific device IDs.

Note: An Access Key’s access restrictions cannot be changed post-creation; however, if scoping the restrictions to a device tag, devices may gain or lose permission to use the Access Key as their tag values are modified.

Additional MQTT Topic Access

Optionally, you may also grant publish/subscribe permissions to additional custom topics for devices connecting to the MQTT broker with the new Access Key.

From the “Additional MQTT Topics” dropdown, select one of the following options:

• All topics: All devices using this Access Key to publish or subscribe to all custom topics within the application.
• No additional topics: Devices using this access key may only publish or subscribe to their own topics.
• Only the following topics …: When selecting this option, you must define at least one topic that devices using the Access Key may publish or subscribe to. You may define multiple topics for each operation, and the topic definitions support string templates.
• All but the following topics …: Selecting this option is similar to “Only the following topics …”, except the listed topics are the only ones the Access Key does not provide access to.

Note: Unlike access restrictions, additional MQTT topic access may be changed post-creation.

Result

Finally, define a path on your payload where the new Access Key should be placed. This field is required because the Access Key’s secret cannot be retrieved post-creation. Therefore, ensure that your workflow is making use of the Access Key later in its run.

For example, when allowing Experience Users to dynamically register new devices, it is common practice to first create a device using the Device: Create Node, and immediately create a new Access Key restricted to that new device. The Endpoint Reply Node responding to the request should include at least the new device’s ID, along with the Access Key’s key and secret properties.

If creation of the Access Key fails, the object placed at the specified payload path will instead be an object describing the error.

Node Example

Given the node configuration in the screenshots above, and an input device with an ID of “aaaabbbbccccddddeeeeffff” and an mfgGroup tag value of “ABC123”, successful Access Key creation placed on the path working.newDevice.accessKey will result in the following object placed at that path:

{
  "secret": "*****REDACTED*****",
  "id": "605e39206a3df30006a8ac13",
  "applicationKeyId": "605e39206a3df30006a8ac13",
  "status": "active",
  "key": "9743b6fa-81d6-4148-92a4-ee2a0704d686",
  "lastUpdated": "2021-03-26T19:42:24.425Z",
  "creationDate": "2021-03-26T19:42:24.366Z",
  "applicationId": "5e6a7b69e5a5e100073a5cce",
  "subTopics": ["ABC123/alerts"],
  "pubTopics": ["ABC123/alerts"],
  "filterType": "whitelist",
  "description": "",
  "deviceTags": [],
  "deviceIds": ["aaaabbbbccccddddeeeeffff"]
}

Note: In the Debug Panel, the secret will appear as ”*****REDACTED*****” for security purposes. However, the actual Access Key secret is available on the payload at that path.

Node Errors

If we replace {{working.newDevice.id}} with a template referencing an invalid ID - such as {{working.doesNotExist}} - the Access Key: Create Node will output the following to our specified result path:

{
  "message": "deviceIds.0 pattern mismatch",
  "type": "Validation"
}

Related Nodes

• Device: Create Node
• Device: Update Node