Refreshable token

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

Introduction

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

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

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

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

Docuware

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

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

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