References - ThreatConnect API Base URL and Signatures

Owned by John Hall (Unlicensed)
Last updated: Jun 09, 2020
3 min read

Overview

The purpose of this document is to expand on the concept of the base URL and signature for the ThreatConnect REST API. This document provides specific examples for how support of the base URL and signature should be implemented in an External REST Integration.

ThreatConnect API Base URLs

Overview

The ThreatConnect API’s base URL is the non-endpoint portion of the URL. For instance, this is a full API path:

https://api.threatconnect.com/v2/owners

In this instance, the base URL being used is https://api.threatconnect.com and the endpoint is /v2/owners.

For ThreatConnect Dedicated Clouds and On-Prem instances, a full API path may look like this:

https://myinstance.domain.com/api/v2/owners

Because of this, the base URL being used is https://myinstance.domain.com/api and the endpoint is /v2/owners in this example.

Implementation

Within your application, you should expect someone to properly configure their base URL based on their instance’s configuration. Your implementation should remain flexible enough to interpret the configuration regardless of what is expressed above. Therefore, we recommend that you always require the following fields for the REST API:

  • API Access ID

  • API Secret Key

  • Base URL (as specified above)

It is up to each end-user of your solution to properly configure this base URL. They should be familiar with this information but, in the event that they are not certain, their system administrator or Support contacts could specifically assist them in determining what value to use for an external system.

In your implementation of this logic, you should avoid doing any of the following:

  • Automatically making decisions based on the hostname of the URL provided. You should remain agnostic to this at all times.

  • Attempting to guess the correct base URL path based on inputs. You should use the method we’ve provided to ensure that this always works and remains flexible.

ThreatConnect API Signature

Path for Calculation

Given the definition of the API Base URL above, you may be left wondering how to properly calculate the API signature. The API signature should always be calculated using the actual path called from the API URL, not just the literal API endpoint. Take this example below:

The request URL is https://myinstance.domain.com/api/v2/indicators/addresses/88.77.66.55?includeAdditional=true. With that in mind, we can determine the following:

  • The literal API endpoint is /v2/indicators/addresses/88.77.66.55?includeAdditional=true as this is the call we’re making.

  • The actual path (everything beyond the hostname) is /api/v2/indicators/addresses/88.77.66.55?includeAdditional=true. This is the value we must use in signature calculation.

The logic in your integration must take this into account. It is recommended that you always form your API calls in this way: Base URL + API endpoint. If you’ve followed the Base URL guidance above, you will always end-up with the full request URL. With this complete URL, you would then extract everything after the hostname component (including the leading /) for signature calculation.

The specific method for signature calculation is described in detail here. Be sure to see the Hello World example script provided as a practical example. In addition, a JavaScript example is available in https://threatconnect-techpartners.atlassian.net/wiki/spaces/DP/pages/166330369.

Troubleshooting Signature Calculations

A common issue that you may come across is not properly calculating your signature for the REST API. For this reason, we’ve provided practical examples that you can use to validate the output of your own implementation of the signature method. See these examples:

If you run into problems with your own signature calculation method, an easy way to test what you provide against a known, working example is to compare the different points of calculation. For instance:

  • Compare the timestamp formats to make sure you’re generating the correct timestamp format.

  • If the timestamp is correct, substitute the timestamp you’ve generated in your app into the example using the exact same URL path. You should receive identical results. If you do not, you should check your calculation logic to match the example we’ve provided until they match with identical timestamps and paths.