The EWLogin function is used to create JSON Web Tokens (JWT). These are access tokens used to retrieve data with REST. With JWT, the user credentials are used only once, when the user requests the access token. After a token is generated, the same token is used to authenticate the session until the token expires or is closed out.

Tokens must be refreshed before they expire. The default expiration time for the tokens is 15 minutes, but this value can be changed by creating a Text or Long Integer global variable in your KB named token_expires_in.

Generating JSON Web Tokens

In order to get an access token, use the /ewws/EWLogin method. The response is provided in JSON format. 

Request DescriptionRequest Response

Type of REST request - POST
HTTP-headers - Content-Type: plain/text
URL - /ewws/EWLogin

Request parameters (they can be filled to request body):
$KB - URL-encoded KB name
$login - URL-encoded login
$password - URL-encoded password
$lang - URL-encoded language; by default - en

Type - JSON

Fields:
access_token - access token
refresh_token - token for refreshing non expired access token
expiration_time_unit - time unit; by default - minute
expires_in - expiration time in units; by default is 15 minutes
authentication_scheme - authentication scheme; by default - Bearer

$ curl -is -X POST --header "Content-Type: plain/text" "https://your.server.com/ewws/EWLogin?%24KB=Demo&%24login=admin&%24password=*****&%24lang=en"
 
 
HTTP/2 200
server: nginx
Date: Fri, 24 Jan 2020 16:39:54 GMT
content-length: 482
strict-transport-security: max-age=31536000; includeSubDomains
x-frame-options: SAMEORIGIN
strict-transport-security: max-age=31536000; includeSubDomains
x-frame-options: SAMEORIGIN
strict-transport-security: max-age=31536000; includeSubDomains
{"access_token":"XXeyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxNTJfYWRtaW4iLCJyb2xlIjoiUkVTVCIsInNlYW5jZSI6IjQ0MTM4NzAiLCJleHAiOjE1OTY3MTAzMTUsImlhdCI6MTU5NjcwOTQxNX0.t9Kb1WCF8ltIuO7ylEdm0FSYFQKMsbYRO45gV760bn4","refresh_token":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxNTJfYWRtaW4iLCJyb2xlIjoiVE9LRU4iLCJzZWFuY2UiOiI0NDEzODcwIiwiZXhwIjoxNTk2NzEwMzc1LCJpYXQiOjE1OTY3MDk0MTV9.8UUX1QvSLnG_7LjmaumCFFGvRCphQlJQV61e8fRVLWg","expiration_time_unit":"minute","expires_in":15,"authentication_scheme":"Bearer "}

Using JSON Web Tokens

To use the generated access token, add the Authorization header to your request by combining the authentication_scheme and access_token values on one line. These values come from the response received when generating the token.

If you received the values in the example above, the header would be: 

Authorization: Bearer XXeyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxNTJfYWRtaW4iLCJyb2xlIjoiUkVTVCIsInNlYW5jZSI6IjQ0MTM4NzAiLCJleHAiOjE1OTY

$curl -is -X GET --header "Authorization: Bearer XXeyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxNTJfYWRtaW4iLCJyb2xlIjoiUkVTVCIsInNlYW5jZSI6IjQ0MTM4NzAiLCJleHAiOjE1OTY3MTAzMTUsImlhdCI6MTU5NjcwOTQxNX0.t9Kb1WCF8ltIuO7ylEdm0FSYFQKMsbYRO45gV760bn4" "https://your.server.com/ewws/EWRead?%24KB=Demo&%24table=case&%24lang=en&id=82"


Refreshing JSON Web Tokens

To refresh an access token, use the /ewws/EWLogin method.

Request DescriptionRequest Response

Type of REST request - POST
HTTP-headers - Authorization
URL - /ewws/EWLogin

Request parameters (they can be filled to request body):
$KB - URL-encoded KB name
$lang - URL-encoded language; by default - en

Request body:
refresh_token - your refresh token

Type - JSON

Fields:
access_token - access token
refresh_token - token for refreshing non expired access token
expiration_time_unit - time unit; by default - minute
expires_in - expiration time in units; by default is 15 minutes
authentication_scheme - authentication scheme; by default - Bearer

$ curl -is -X POST --header "Authorization: Bearer XXeyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxNTJfYWRtaW4iLCJyb2xlIjoiUkVTVCIsInNlYW5jZSI6IjQ0MTM4NzAiLCJleHAiOjE1OTY3MTAzMTUsImlhdCI6MTU5NjcwOTQxNX0.t9Kb1WCF8ltIuO7ylEdm0FSYFQKMsbYRO45gV760bn4" --data "refresh_token=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxNTJfYWRtaW4iLCJyb2xlIjoiVE9LRU4iLCJzZWFuY2UiOiI0NDEzODcwIiwiZXhwIjoxNTk2NzEwMzc1LCJpYXQiOjE1OTY3MDk0MTV9.8UUX1QvSLnG_7LjmaumCFFGvRCphQlJQV61e8fRVLWg" "https://your.server.com/ewws/EWLogin?%24KB=Demo&%24lang=en"
 
 
HTTP/2 200
server: nginx
date: Thu, 06 Aug 2020 10:29:33 GMT
content-length: 482
strict-transport-security: max-age=31536000; includeSubDomains
x-frame-options: SAMEORIGIN
strict-transport-security: max-age=31536000; includeSubDomains
x-frame-options: SAMEORIGIN
strict-transport-security: max-age=31536000; includeSubDomains
 
 
{"access_token":"XXeyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxNTJfYWRtaW4iLCJyb2xlIjoiUkVTVCIsInNlYW5jZSI6IjQ0MTM4NzAiLCJleHAiOjE1OTY3MTA2NzMsImlhdCI6MTU5NjcwOTc3M30.7o8Ud1JlvcGMCMo_V_489FTHrw94T-heaD1sqFaG2B8","refresh_token":"XXeyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxNTJfYWRtaW4iLCJyb2xlIjoiVE9LRU4iLCJzZWFuY2UiOiI0NDEzODcwIiwiZXhwIjoxNTk2NzEwNzMzLCJpYXQiOjE1OTY3MDk3NzN9.A4EoQDGW7NC4lmmQs4a4pl9RfrxjVXohJjtbgDD0pbI","expiration_time_unit":"minute","expires_in":15,"authentication_scheme":"Bearer "}


JWT Logout Operations

To close out the session associated with a token, use the /ewws/EWLogout method.

Request DescriptionRequest Response

Type of REST request - POST or GET
HTTP-headers - Authorization
URL - /ewws/EWLogout

Request parameters (they can be filled in request body):
$KB - URL-encoded KB name
$lang - URL-encoded language; by default - en

Response code 200 (OK)
$ curl -is -X GET --header "Authorization: Bearer XXeyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIyX2FkbWluIiwicm9sZSI6IlJFU1QiLCJzZWFuY2UiOiI0MiIsImV4cCI6MTU3OTg4NjMzNywiaWF0IjoxNTc5ODg1NDM3fQ.h94qpNaZfqPgsEEHZbpopUOySiUE9MJ4lrnI_pmu_W8" "https://your.server.com/ewws/EWLogout?%24KB=Demo&%24table=case&%24lang=en"
 
 
HTTP/1.1 200 OK
Connection: keep-alive
Content-Type: charset=UTF-8
Content-Length: 0
Date: Fri, 24 Jan 2020 17:07:37 GMT