# 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"
  }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.locoia.com/connectors/authentication/refreshable-token.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.