Skip to main content

Managing API Keys and Authenticating to the LinkSquares APIs

  • Updated

Overview 

LinkSquares APIs are secured from unauthorized use by restricting calls to those that provide proper authentication credentials. The credentials are in the form of an API Key, which is a unique alphanumeric string that the system uses to identify your company’s data.

These keys should be stored in a password manager or an alternative safe location since having access to them is the equivalent of access to your agreements.

Note: LinkSquares API Tokens are shared across Analyze and Finalize. The same token can interact with either application. 

Authentication

LinkSquares APIs utilize a common API key-based authentication, which is invoked by embedding the API key in the request header. API endpoints are REST/HTTPS unless otherwise specified, with request and response data in JSON format.

  • Each API key is tied to a user and company.
  • Best practice is to use a service account vs. a user account (Example: linksquares_api@companydomain.com)
  • The API user must be configured as an Analyze or Finalize Administrator. The IT Administrator role cannot be used for the User account that manages the API key.
  • The API Key must be included as an x-api-key Header to every API request.
    • Value = x-api-key
    • The API Gateway uses JWT (JSON Web tokens) as additional security to securely transmit information between systems

Authentication Examples

Adding your API key should be quick and easy. Here is a quick cURL example from which you can build.  Swap out XXXXX for your API key.

curl --location 'https://api.linksquares.com/api/analyze/v1/agreements' \
--header 'Content-Type: application/json' \
--header 'x-api-key: XXXXX'

If you're working in Postman, this will often look like the below, again, swap out the XXXXX for your key:

Creating an API Key 

LinkSquares Administrators can create API keys in the LinkSquares web app settings. 

To begin, go to Settings from the app selector.

Select API Keys.

To create an API key, press the GENERATE API KEY button.

Generate_API_Key.png

Disabling an API Key 

If you ever wish to disable the API key (e.g., it was on a laptop that was lost or stolen), you can log in to LinkSquares and disable the key. 

Once you disable the compromised key, you can create another one. In other cases, your security policy may dictate that API keys are rotated every 90 or 120 days. The process is the same. Once the option to disable a key is selected, please allow up to five minutes for the change to go into effect.

For the relevant API key, click the Enabled toggle. 

Enabled_Toggle.png

The Disable API Key modal will appear and prompt you to confirm. Click SAVE.

Disable_Key_Pop_Up.png

The API key is now shown as Disabled. 

Disabled_Toggle.png

Disabled keys can be re-enabled by clicking the same toggle.

Deleting an API Key 

If you no longer need an API key, it can be deleted by clicking the trash icon. 

Delete_Icon.png

The Delete API Key modal will appear and prompt you to confirm. Click DELETE.

Delete_API_Key_Pop-Up.png

There is no way to undo the deletion of a key. Once deleted, please allow up to five minutes for the change to go into effect.

Using HTTPS for the API Gateway 

The API Gateway requires using HTTPS as a method of ensuring encryption and security of the public API. If HTTP is used then the user will receive a message detailing that a connection was not able to be established.

Related articles