Running REST API Calls with Postman on EMS and LSR
• Calling REST API calls directly on the ThingWorx Platform requires authentication set, using the userid / password or appKey header.
 |
username and password are Base64 encoded in the Authorization Header. As the delimiter symbol is a ":" (colon) between username and password (e.g. "ptc:ptc" in the example above) the username must not contain a ":" (colon) character. Otherwise, the requests will fail with an error message, HTTP 401 Status - Authentication Required .
|
• The EMS / LSR REST API calls need to be called with the following configuration:
◦ Instead of supplying credentials in the Headers section in Postman, you can use the Authorization tab.
◦ The Type must be set to Basic Auth and a valid username.password combination must be provided.
◦ In the Headers, Content-Type and Accept must be present. Postman will automatically add an Authorization key, based on the values provided in the Authorization tab.
◦ In the Headers, you must also include the x-csrf-token header. The token is a random string used for Cross-Site Request Forgery (CSRF) protction in the EMS. When authentication and CSRF tokens are enabled on the EMS, the EMS will return a random CSRF token with each response. That token must be used in the next client request. If this token is not included or is incorrect, the request will fail with a 401 Unauthorized error.
As of v.5.4.2, CSRF token support is provided in the REST API for the EMS and LSR. This support is enabled by default. For more information, refer to the section below, CSRF Token Support in REST API for EMS and LSR.
• Use the following URLs to test the authentication mechanism:
◦ EMS — Verify the System Repository name property.
▪ https://<ems_host>:8000/Thingworx/Things/SystemRepository/Properties/name.
▪ Should return "name": "SystemRepository".
◦ EMS — Verify the isConnected property of the LocalEMS.
▪ https://<ems_host>:8000/Thingworx/Things/LocalEms/Properties/isConnected.
▪ Should return "isConnected": true.
◦ LSR — Verify that you get a 200 OK response when connecting to the LSR.
▪ https://<lsr_host>:8000/
▪ Should return 200 OK HTTP response with no content in the body.
|
|
It is highly recommended that you use a secure password with more than three letters, as used in above example. For more information, refer to Password policy.
To learn what REST services are available for the LSR, refer to the /help on the LSR in a web browser.
|
CSRF Token Support in REST API for EMS and LSR
As of v.5.4.2, CSRF token support is provided in the REST API for the EMS and LSR. The support for CSRF tokens requires any requests from a client that can change state (such as POST, PUT or DELETE) include a CSRF token in the headers of their request. This token will be provided by the server and put into the response header with the key x-csrf-token. The client must include this same header and token value with any request that can change state.
The token will change periodically based on the http_server_csrf_token_rotation_period (EMS) and scripts.script_resource_csrf_token_rotation_period (LSR) values set in config.json and config.lua, respectively. The default period is every 10 minutes.
Neither the EMS nor the LSR require changes or configuration updates to support CSRF tokens. The tokens are enabled by default. Applications that use the REST interface of the EMS or LSR will need to be updated to include the CSRF token, or CSRF protection must be disabled (not recommended). You can disable CSRF protection by adding the line enable_csrf_tokens = false in the http_server struct of config.json (EMS) or scripts.script_resource_enable_csrf_tokens = false` in config.lua (LSR).
CSRF protection is enabled only when authentication is enabled as well. If authentication is disabled, no token values will be used. PTC recommends always using TLS, enabling authentication, and encrypting sensitive credentials in configuration files.
In addition to the CSRF token support, changes have been made in v.5.4.2 to how the Lua Script Resource’s /script and /scriptcontrol REST endpoints work out-of-the-box. By default, you will not be able to use these endpoints to dynamically create, update, delete, or restart scripts using the REST API. Any requests to these services will result in a 405 – Method Not Allowed error. This feature can be enabled by adding the line scripts.script_resource_enable_rest_services = true to your config.lua