# Refreshable token

### Introduction <a href="#introduction" id="introduction"></a>

The **Refreshable Token** authentication mechanism works similarly to OAuth2.

However, instead of the user logging into a Connector’s page, users enter their API credentials directly into Locoia.

Locoia then:

* Sends the credentials to the authentication server.
* Retrieves a refresh token.
* Uses the refresh token to regularly obtain valid access tokens.

### Header Configuration <a href="#header" id="header"></a>

The typical header structure for Refreshable Token authentication (except for `header_key`) is:

```json
{
  "encode": false,
  "token_in_header": true,
  "content_type": "application/json",
  "header_key": "Authorization",
  "token_format": "{{token}}",
  "token_prefix": "Bearer {{token_format}}"
}
```

### Authentication Configuration (Standard)

Example for **snov.io**:

```json
{
  "refreshable_token": {
    "auth_form": [
      {
        "name": "username",
        "title": "client_id",
        "type": "text",
        "required": true
      },
      {
        "name": "password",
        "title": "client_secret",
        "type": "password",
        "required": true
      }
    ],
    "config": {
      "authorization_request_body_template": "{}",
      "authorization_request_method": "GET"
      "authorization_request_url": "https://api.snov.io/v1/oauth/access_token?client_id={{ username }}&client_secret={{ password }}&grant_type=client_credentials",
      "response_access_token_path": "access_token",
      "response_refresh_token_path": null,
      "refresh_request_body_template": null,
      "refresh_request_url": null,
      "authorization_request_headers": "{\"Content-Type\" : \"application/x-www-form-urlencoded\"}"
    }
  }
}
```

### **Required parameters**

* `authorization_request_url`  URL for the initial token request.
* `authorization_request_body_template`  Template for the body. Pass an empty string (`""`) if no body is needed.
* `authorization_request_headers`  Headers for the token request.
* `response_access_token_path`  Path to extract access token from response.

### Required Parameters for Separate Refresh Endpoints

* `refresh_request_url`  URL to request a new access token using the refresh token.
* `refresh_request_body_template`  Template for the refresh body. Pass an empty string (`""`) if no body is needed.
* `refresh_request_headers`  Headers for the refresh request.
* `response_refresh_token_path`  Path to extract refresh token from response.

### **Optional parameters**

* `authorization_request_method` is optional to have the request be a GET, which is rarely the case but happens. The default is POST
* `refresh_response_access_token_path` is an optional path to the access token for the refresh request. In case it's not specified `response_access_token_path` will be used for the refresh request as well
* `response_access_token_path_in_header` is an optional path to the access token for the refresh request, which needs to be used, if the access token is in the header of the response
* `response_access_token_path_in_cookie` is used in order to retrieve a cookie value from the response as the access token. As there can be multiple cookies in the response, a unique string from the desired cookie needs to be specified as it's value.
* `refresh_response_refresh_token_path` is an optional path to the access token for the refresh request. In case it's not specified `response_refresh_token_path` will be used for the refresh request as well

### Examples <a href="#examples" id="examples"></a>

#### Docuware <a href="#docuware" id="docuware"></a>

Docuware uses a Cookie-based authentication and additionally requires the same `User-Agent` header for all requests:

```json
{
  "refreshable_token": {
    "auth_form": [
      {
        "name": "domain",
        "title": "Domain",
        "type": "text",
        "placeholder": "company-name.docuware.cloud",
        "required": true,
        "info": "Excluding 'https://'"
      },
      {
        "name": "username",
        "title": "Username",
        "type": "text",
        "required": true
      },
      {
        "name": "password",
        "title": "Password",
        "type": "password",
        "required": true
      }
    ],
    "config": {
      "authorization_request_url": "https://{{ domain }}/docuware/platform/Account/Logon?UserName={{ username }}&Password={{ password }}&RedirectToMyselfInCaseOfError=false&RememberMe=false&LicenseType=",
      "authorization_request_body_template": "Password={{ password }}&UserName={{ username }}&HostID=locoia",
      "authorization_request_headers": "{\"Content-Type\": \"application/x-www-form-urlencoded\", \"User-Agent\": \"curl/7.84.0\"}",
      "response_access_token_path_in_cookie": ".DWPLATFORMAUTH"
    }
  }
}
```

In the **Header** configuration, the same `User-Agent` needs to be specified:

```json
{
  "token_in_header": true,
  "header_key": "Cookie",
  "content_type": "application/json",
  "token_prefix": ".DWPLATFORMAUTH={{token_format}}",
  "token_format": "{{token}}",
  "custom_headers": {
    "User-Agent": "curl/7.84.0",
    "Accept": "application/json"
  }
}
```