---
title: "REST - Login"
canonical: "https://help.agiloft.com/space/HELP/43714204/REST+-+Login"
format: markdown
---
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 an Integer Constant global variable in your KB named token_expires_in. If you want to increase the expiration time, set token_expires_in to a value higher than 15, up to 60.

## Generating JSON Web Tokens

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

| **Request Description** | **Request Response** |
| --- | --- |
| Type of REST request - **POST**  
HTTP-headers - **Content-Type: plain/text**  
URL - **/ewws/EWLogin**<br>Request parameters:  
**$KB** - URL-encoded KB name  
**$login** - URL-encoded login  
**$password** - URL-encoded password  
**$lang** - URL-encoded language; by default - en | Type - **JSON**<br>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 |

<details>
<summary>Request Example</summary>

```
$ 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 "}
```
</details>

## 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*

<details>
<summary>Example Header</summary>

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


## Refreshing JSON Web Tokens

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

| **Request Description** | **Request Response** |
| --- | --- |
| Type of REST request - **POST**  
HTTP-headers - **Authorization**  
URL - **/ewws/EWLogin**<br>Request parameters:  
**$KB** - URL-encoded KB name  
**$lang** - URL-encoded language; by default - en<br>Request body:  
**refresh_token** - your refresh token | Type - **JSON**<br>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 |

##### **Refresh Example**

```
$ 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 Description** | **Request Response** |
| --- | --- |
| Type of REST request - **POST** or **GET**  
HTTP-headers - **Authorization**  
URL - **/ewws/EWLogout**<br>Request parameters:  
**$KB** - URL-encoded KB name  
**$lang** - URL-encoded language; by default - en | Response code 200 (OK) |

<details>
<summary>Logout Example</summary>

```
$ 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
```
</details>

# Error Codes

The below error codes are for EWLogin only, but are not an extensive list of possible error codes. For any errors not listed here, consult the General Error Codes section of [REST Interface](https://agiloft-public.atlassian.net/wiki/spaces/HELP/pages/43715778).

|  |  |  |  |
| --- | --- | --- | --- |
| Scenario | Type | Code | Description |
| When the token is NOT NULL and refreshToken is not provided in request | VALIDATION | 400 | EWWrongDataException   → No value for 'refresh_token' parameter specified. |
| When there is any issue with refreshToken | VALIDATION | 400 | EWWrongDataException   → Wrong value for 'refresh_token' parameter specified. |
| When the provided refreshToken is invalid or doesn’t match the actual value | VALIDATION | 400 | EWWrongDataException   → Wrong value for 'refresh_token' parameter. |
| When the refreshToken has expired | VALIDATION | 401 | EWAuthException →   Refresh Token is expired |
| When the user doesn’t have permission to login to the KB | VALIDATION | 403 | EWPermissionException → User <userName> lacks   permission log in |