CIMPLICITY REST interfaces provide capabilities to access CIMPLICITY remotely through web interface(https), which allows you to build client applications on any OS, or browser based client applications using the hypermedia provided by CIMPLICITY.
Following capabilities are supported from REST API:
Configuration capabilities:
- Points
- Objects
- Users
- Roles
- SQL connections
- Historian connections
Runtime capabilities:
- Start/Stop project
Security and Authentication
From CIMPLICITY 2023 onwards, the following types of authentication methods are supported for REST APIs:
Basic Authentication
You can use basic authentication when CIMPLICITY is used as an identity provider. With this authentication method, you can use native user/domain user credentials to authenticate REST APIs.
Project API: All REST APIs where project is specified are referred as project APIs. You need to acquire sessionId to use these APIs.
Acquiring a session:
To get the session id you need to use following REST API:
URL: /cim-config/v1/projects/<PROJECTID>/session
Headers:
Authentication: basic auth. (use credentials of any user in the project)
Response: JSON object
{
"inactivityTimeout": 1200000,
"privileges": -1,
"refreshInterval": 900000,
"sessionId": "LCXVttwj5hWX7T/bQpIEbROAq+ZjhUnJtx8oo1zsRaZp8NgN7KPCJCbRHKGVetgIYKt+SBua4uGsmFFlILs0tV0b5nNggPlzI9Nev5UyFKZ5ZwKoGiOS7YQbltOrBR3H/CZhtAeL7ZEQCQIndPbWcWEJVgiRnD57YKh/bITQRQ4wVpN+A8DLgTmtGpJk8b7Bj4FWY6RwtdskNNBLUAKgrgPSuQk58fwrxyfyiOCRorLVYZgbCETyQXit27z3xb7kEedcOa3TGLMz+i5ohob7AnqDHBq/tAWjzwuTHGLGRRZMKnqDJyqaQEYodGpUUF0N"
}
SessionId received is valid for 15 minutes by default.
All project APIs use basic authentication with sessionId as payload.
Example: If you want to create a point using /cim-config/v1/projects/<PROJECTID>/points, you need to add an authorization header as follows.
Basic LCXVttwj5hWX7T/bQpIEbROAq+ZjhUnJtx8oo1zsRaZp8NgN7KPCJCbRHKGVetgIYKt+SBua4uGsmFFlILs0tV0b5nNggPlzI9Nev5UyFKZ5ZwKoGiOS7YQbltOrBR3H/CZhtAeL7ZEQCQIndPbWcWEJVgiRnD57YKh/bITQRQ4wVpN+A8DLgTmtGpJk8b7Bj4FWY6RwtdskNNBLUAKgrgPSuQk58fwrxyfyiOCRorLVYZgbCETyQXit27z3xb7kEedcOa3TGLMz+i5ohob7AnqDHBq/tAWjzwuTHGLGRRZMKnqDJyqaQEYodGpUUF0N
Refresh a session:
As the sessionId is valid only for 15 minutes, you need to refresh token before it expires using refreshsession API
url: /cim-config/v1/projects/<PROJECTID>/refeshsession
Headers:
Authentication: Use basic authentication with sessionId as a payload (same as the project API authentication).
Bearer Token Authentication
You can use bearer token authentication when Proficy Authentication Server is used as an identity provider. To use this authentication method, you must configure Proficy Authentication server and enable Proficy Authentication for the project. For more information on Proficy Authentication, refer to the Proficy Authentication section in the CIMPLICITY online documentation. With this authentication method, you can use Proficy user credentials to authenticate REST APIs.
You can either get token directly from REST APIs provided by Proficy Autnetication or use any utilities like Curl to get the token. See the below examples on genrating token using Curl:
cURL command format for generating an oauth token for clients:
curl -u <client ID>:<client secret> https://<node name>:8443/uaa/oauth/token -d 'grant_type=client_credentials'
Example:
curl -u server1.admin:adminsecret https://server1:8443/uaa/oauth/token -d 'grant_type=client_credentials'
cURL command format for generating an oauth token for UAA users:
curl -d "client_id=<value>&client_secret=<value>&grant_type=password&username=<value>&password=<value>&token_format=opaque&response_type=token" https://<node name>:8080/uaa/oauth/token
Example:
curl -d "client_id=server1.admin&client_secret=adminsecret&grant_type=password&username=user1&password=pwd123&token_format=opaque&response_type=token" https://server1:8080/uaa/oauth/token
Computer APIs:
Following APIs are computer APIs and use basic authentication. These APIs can be used to work with multiple projects on a computer.
cim-config/v1/user-config
cim-config/v1/rest-settings
You need to create a computer user for working with above APIs. You can create a computer user with command line utility RegisterComputerUser.exe, by default you do not create a computer user. Computer user credentials can be used to fill details in Basic Authentication Header.
REST APIs:
Following APIs are supported: