Refreshable token

Here are all details about configuring Connectors to authenticate with Refreshable Tokens

Introduction

The refreshable token authentication covers authentication mechanism which work similarly to OAuth2.

However, instead of the user logging into the Connector's login page directly and passing a token back to Locoia, the user enters their API credentials directly in Locoia.

Just like with OAuth2, Locoia then receives a refresh token (based on the entered credentials) which is then used to retrieve a valid access token.

Header

The header for refreshable token is, except for the header_key, usually configured like this:

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

Authentication Configuration

The below example is for snov.io.

{
  "refreshable_token": {
    "auth_form": {
      "username": {
        "title": "Client ID",
        "type": "text",
        "required": true
      },
      "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

• authorization_request_body_template - if no template needs to be passed, pass an empty string ""

• authorization_request_headers

• response_access_token_path

Required parameters for different REFRESHING endpoint

• refresh_request_url

• refresh_request_body_template - if no template needs to be passed, pass an empty string ""

• refresh_request_headers

• response_refresh_token_path

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

Docuware

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

{
  "refreshable_token": {
    "auth_form": {
      "domain": {
        "name": "domain",
        "title": "Domain",
        "type": "text",
        "placeholder": "company-name.docuware.cloud",
        "required": true,
        "info": "Excluding 'https://'"
      },
      "username": {
        "name": "username",
        "title": "Username",
        "type": "text",
        "required": true
      },
      "password": {
        "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:

{
  "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"
  }
}