Application Keys
Application keys are security tokens encrypted in the ThingWorx database that can be used to log in to the ThingWorx application instead of using standard credentials.
You can pass application key tokens on the header in the URL of a request. The request is run using the security context of the user associated with the application key. By default, a session is not created when a request is made using an application key. This is the recommended way for other systems and applications to make a request to the ThingWorx application. However, if you want to create a session, you can use the following query parameter in addition to passing in the application key token:x-thingworx-session=true.
When viewing a mashup via a URL and using an application key, create a session by adding x-thingworx-session=true. Without a session, subsequent requests require authentication using the standard HTTP basic authenticator. After the x-thingworx-session=true query parameter, you include #mashup=[your mashup name].
 |
You should always use the security concept of the least privilege when creating and assigning privileges to application keys. It is not a best practice to assign a member of the Administrator group to an application key. A warning will be displayed if you attempt to create an application key based on a user with administrator privileges.
|
Application Key Properties
|
Property Name
|
Description
|
||
|---|---|---|---|
|
Name
|
Word or phrase that identifies this key. Required field.
|
||
|
Avatar
|
An image that can be uploaded to visually represent the application key.
|
||
|
Description
|
The description of the application key.
|
||
|
Project
|
The work or group associated with this key.
|
||
|
Tags
|
Model tags you can use to group or categorize the application key.
|
||
|
IP Whitelist
|
The list of IPs allowed to access ThingWorx using the application key. Separate the IPs with a comma. If left blank, any IP may use the application key.
|
||
|
Client Name
|
User-definable field that can represent anything, such as the client associated with the application key or an IP address. ThingWorx disregards any values assigned to this field.
|
||
|
User Name Reference
|
The user name that is associated with the application key. Required field.
|
||
|
Key ID
|
The ThingWorx-generated key value. The key ID cannot be edited.
|
||
|
Expiration Date
|
The expiration date for the application key. If an expiration date is not specified, the default value in the User Management Subsystem is used. For ThingWorx 8.1 and later, application keys expire 24 hours after their creation if the expiration date is not specified or if the Application Key Lifetime (sec) value in the user management subsystem is not changed.
|
||
|
Last Modified Date
|
The date and time when the application key was last modified.
|
||
|
Home Mashup
|
The default mashup associated with the application key.
|
||
|
Documentation
|
Optional notes or background information that describes how or why this is used within the environment.
|
Creating an Application Key
Follow the steps below to create an application key. The created key assumes the security settings granted to the associated user in the User Name Reference field.
1. In ThingWorx Composer, click New.
2. Scroll down and select Application Keys.
3. Type a Name.
4. If desired, select or enter Description, Project, and Tags for this key.
5. In the User Name Reference field, select the user associated with the application key.
6. Fill any optional fields desired, including IP Whitelist, Client Name, Home Mashup, Avatar, Expiration Date, or Documentation.
|
|
If an Expiration Date is not set, a value is calculated from the creation date of the application key entity plus the Application Key Lifetime (sec) setting in the user management subsystem.
|
7. Click Save.
8. The application key displays in the Key ID field.
Deleting an Application Key
Although an expiration date can be specified for an application key, they are not automatically deleted when they expire. You can write ThingWorx application logic that periodically iterates through and deletes expired application keys. See Application Key Services. To manually delete an application key:
1. In Composer, browse All.
2. Scroll down to the SECURITY section.
3. Expand the section, if necessary, and locate Application Keys.
4. Select an application key by clicking in the checkbox to the left of the name.
5. Click the Delete button.
Creating an Application Key Through a Service
To create an application key through a service, use the following example:
var params = {
clientName: undefined /* STRING */,
name: undefined /* STRING */,
description: undefined /* STRING */,
project: undefined /* STRING */,
whitelist: undefined /* STRING */,
user: undefined /* USERNAME */,
tags: undefined /* TAGS */,
expirationDate: undefined /* DATETIME */
};
// no return
Resources["EntityServices"].CreateApplicationKey(params);
//Get the generated Key's actual appKey value
var KeyID = ApplicationKeys["YOURKEYNAME"].GetKeyID();
clientName: undefined /* STRING */,
name: undefined /* STRING */,
description: undefined /* STRING */,
project: undefined /* STRING */,
whitelist: undefined /* STRING */,
user: undefined /* USERNAME */,
tags: undefined /* TAGS */,
expirationDate: undefined /* DATETIME */
};
// no return
Resources["EntityServices"].CreateApplicationKey(params);
//Get the generated Key's actual appKey value
var KeyID = ApplicationKeys["YOURKEYNAME"].GetKeyID();
|
|
If an Expiration Date is not set, a value is calculated from the creation date of the application key entity plus the Application Key Lifetime (sec) setting in the user management subsystem.
|
Initial Application Key Setup and First Connection Best Practice
Devices should always be brought online in a development sandbox or simulated in a development sandbox, whenever possible. Once a device is ready for production, new application keys should be created for each device that will be on the application's edge network. After a unique application key has been created and deployed to the device in question, that device should be monitored when it initializes to verify it has successfully connected to the platform.
Application Key Expiration and Rotation
As a best practice, application keys should have a finite expiration date that matches the expected lifecycle of the device that will be consuming the application key credentials. Additionally, it is not recommended that the same application key be used for multiple devices, especially if their lifecycles are different. Once an application key has expired, a new application key should be installed on the device.
Application Key Expiration for Critical Applications
If there is not a system to deliver a new application key to the device, the expiration key on the application key can be updated to allow an extended service life. This is not a recommended best practice, but it can be used as a workaround when business critical data may be lost. It is important to note that extending the lifecycle of the application key beyond the expected lifecycle of the device can introduce security threats to critical application infrastructure.
Related Links