2021.1

Registration and authentiaction

Application registration

WEBCON API uses the HTTP method on your request to determinate what action should be performed. The API supports following methods:

In WEBCON BPS you can create and manage all of your applications from the admin panel, which is available at https://[WEBCON Portal address]/adminpanel, e.g. https://dev20.webcon.pl/WEBCONBPS/adminpanel. This panel can only be used by global administrators.

How can you do that?

  1. Open [WEBCON Portal address]/adminpanel in your browser and enter login details (if necessary).
  2. Choose New API application.
  3. Enter the application name, login (in UPN format) and e-mail address. Your login should be unique and UPNs used in the system are not allowed. Allow the impersonation may remain unchecked, we will discuss it later.
  4. Choose Save

The following screenshot shows an example web application registration:

AppRegister-1024x558

Client ID and secret

Application uses both Client ID and Secret to authenticate. ID is generated during application registration while secret can be generated in next screen (after application save). Every application has exactly one Client ID (that cannot be changed) and can have multiple Secrets used in different systems. New secrets can be created by using the ‘Generate new client secret’ button. In the next pop-up we can add key description, which can be used for easier Secrets identification and management. It is important to save newly generated secret, because it will not be shown again and cannot be restored. Keep client ID and key secret as they can be used to access Webcon BPS data and perform actions such as read, edit or delete workflows. You should keep Client Secret as secure as a password, and regularly review the secrets you have created to remove any you no longer need.

Following screenshot shows example of generating a secret:

ClientSecret-1024x565

Impersonation and permissions

API application uses its own permissions that you can grant in WEBCON BPS Designer Studio, just like users or groups. Another option is to use other user permissions via an impersonation, but to do so, first you need to allow API application to impersonate and select the list of applications within which it will be able to do so. This also can be done in edit page in the admin panel.

Authentication

To call WEBCON REST API, your application must acquire an access token, which contains information about your application and the permissions it has. To get an access token, your application has to be registered in WEBCON admin panel. Access tokens are JSON Web Tokens (JWT). They contain claims that web API uses to validate the caller and to ensure that the caller has the proper permissions to perform the operation they’re requesting. To call WEBCON API, you attach the access token as a Bearer token to the authorization header in an HTTP request.

Get access token

To get an access token, your application has to exchange ‘http’ requests with login endpoint. Currently we have two methods of authentication:

Standard OAuth 2.0

Available on endpoint POST /api/oauth2/token. Uses standard oauth client_credentials type authentication flow. This endpoint does not allow impersonation. Below is request in curl for our example application:

curl -X POST "http://dev20/WEBCONBPS/api/oauth2/token" 
-H "accept: text/plain” 
-H "Content-Type: application/x-www-form-urlencoded" 
-d "grant_type=client_credentials&client_id=2be2fd55-5662-4507-b255-1558a7ab9786&client_secret=2tLryMUReamB01Lh7Zwww1ud2qGiWQMRwgc%2F800xub4%3D"

Webcon authentication

Available on endpoint POST /api/login. Here credentials are passed as json in request body. Below is example request without impersonation:

curl -X POST "http://dev20/WEBCONBPS/api/login" 
-H "accept: text/plain" 
-H "Content-Type: application/json " 
-d "{\"clientId\":\"2be2fd55-5662-4507-b255-1558a7ab9786\",\"clientSecret\":\"2tLryMUReamB01Lh7Zwww1ud2qGiWQMRwgc/800xub4=\"}"

To impersonate as other user add to request body additional parameter with user login, as follow:

{
  "clientId": "2be2fd55-5662-4507-b255-1558a7ab9786",
  "clientSecret": "2tLryMUReamB01Lh7Zwww1ud2qGiWQMRwgc/800xub4=",
  "impersonation": {
    "login": "t.green@webcon.pl"
  }
}

Both endpoints return response with token in same format (the access token has been truncated for readability):

{ 
"token": "eyJhbGciOiJIUzI1NiIsI … cD7FSf35S3--z1U7E-qrDMNu0OKi51DY32LA7s8qMlQ" 
}

To call WEBCON API, you attach the access token as Bearer token to the Authorization header in HTTP request. Here’s an example call that returns instance data with id 1:

HTTP/1.1 Host: dev20.webcon.pl 
Authorization: Bearer eyJhbGciOiJIUzI1NiIsI … cD7FSf35S3--z1U7E-qrDMNu0OKi51DY32LA7s 
GET http://dev20.webcon.pl/WEBCONBPS/api/data/v2.0/db/1/elements/1
← Rest APIBasic operations →