Quick Start¶

Creating an API Key¶

To create an API User, please refer to the Creating User Accounts Knowledge Base article.

If you are not able to create an API key using instructions provided in the KB article above, please contact sales@threatconnect.com to discuss pricing.

Using the API¶

For those with a ThreatConnect, Public-Cloud API-user account, the ThreatConnect API is accessible at https://api.threatconnect.com.

Note

If you are working with the ThreatConnect sandbox, the api path is: https://sandbox.threatconnect.com/api. If you are working with a Dedicated Cloud or On-Premise instance of ThreatConnect, please contact your System Administrator for the correct API URL.

For the rest of this document, the base API URL will not be included in any of the endpoints (e.g., the branch for owners will be described as /v2/owners rather than https://api.threatconnect.com/v2/owners). You will be responsible for adding the correct base API URL.

Requests to ThreatConnect API endpoints must be made over HTTPS with a valid Signature (as described in the next section), or a 403 error will be returned.

Each API response is formatted with a status. If the status is “Success,” each response includes a data field with the appropriate response type. If the status is “Failure,” an appropriate error message is provided as to why the request failed.

The API will be versioned as needed to support continued development of the ThreatConnect platform, and existing API versions will be appropriately deprecated. Version 2 (v2) of the API supports write capabilities via HTTP POST and PUT methods. The HTTP GET method is used for read access to resources.

Authentication¶

To authenticate an API call to ThreatConnect, there are two required headers—Authorization and Timestamp—which are detailed below:

A complete request should look like:

GET https://api.threatconnect.com/v2/indicators?owner=Common%20Community HTTP/1.1
 Timestamp: 1513703787
 Authorization: TC 12345678901234567890:PthSlXIA7rNMow1h8wShfvOnTOhxHd+7njUe4MT4ZSs=

Timestamp¶

The required Timestamp header is a nonce in Unix epoch time (generated by Unix shell with the command: date +%s). The value of the Timestamp header should look something like 1513703787.

Note

If the nonce is not within five minutes of the ThreatConnect server’s system time, a Timestamp error will be returned.

Authorization¶

The required Authorization header has the format: TC $ACCESS_ID:$SIGNATURE.

The $ACCESS_ID is the ID of the API user you are using to make requests. If you do not have or do not know the API_ID, ask your System Administrator.

The $SIGNATURE is created by concatenating the API path and query strings, HTTP method, and Timestamp (dicsussed in the previous section) as follows:

/v2/indicators/hosts/example.com?Owner=Common%20Community:GET:1513703787

The result is then signed with the user’s Secret Key using SHA256 to calculate an HMAC (a.k.a. HMAC-SHA256) and base-64 encoded.

The value of the final Authorization header should look something like:

TC 12345678901234567890:PthSlXIA7rNMow1h8wShfvOnTOhxHd+7njUe4MT4ZSs=

Hint

For Python users, you can view how our Python SDK handles authentication here.

Hello World¶

To test API connectivity, start with a request to the /v2/owners branch to return all Organizations and Communities to which the API credentials have access. After you insert your API secret key and access ID, the bash script below will format and send the request:

# specify API details
API_METHOD="GET"
API_PATH='/v2/owners'
API_URL='https://api.threatconnect.com'${API_PATH}

# provide authentication details
API_SECRET='<INSERT YOUR API SECRET KEY HERE>'
API_ID='<INSERT YOUR API ACCESS ID HERE>'

# create the signature
TIMESTAMP=`date +%s`
signature="${API_PATH}:${API_METHOD}:${TIMESTAMP}"
hmac_signature=$(echo -n ${signature} | openssl dgst -binary -sha256 -hmac ${API_SECRET} | base64)
authorization="TC ${API_ID}:${hmac_signature}"

# use this if python is not installed on your system
curl -s -i -H "Timestamp: ${TIMESTAMP}" -H "Authorization: ${authorization}" -X ${API_METHOD} "${API_URL}"

# use this to output the data if python is installed on your system
curl -s -H "Timestamp: ${TIMESTAMP}" -H "Authorization: ${authorization}" -X ${API_METHOD} "${API_URL}" | python -m json.tool

Note

If you receive an error while using the script above, make sure that the API_URL is pointed to the correct API for the instance of ThreatConnect you wish to use.

Get a list of all Owners visible to this user:

GET /v2/owners

JSON Response:

{
  "status": "Success",
  "data": {
    "resultCount": 2,
    "owner": [
      {
        "id": 0,
        "name": "Exemplary Organization",
        "type": "Organization"
      },
      {
        "id": 1,
        "name": "Common Community",
        "type": "Community"
      },
    ]
  }
}

XML Response:

<ownersResponse>
 <Status>Success</Status>
 <Data xsi:type="ownerListResponseData" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Owner xsi:type="organization">
   <Id>0</Id>
   <Name>Exemplary Organization</Name>
   <Type>Organization</Type>
  </Owner>
  <Owner xsi:type="community">
   <Id>1</Id>
   <Name>Common Community</Name>
   <Type>Community</Type>
  </Owner>
 </Data>
</ownersResponse>

Next Steps¶

From here, find a topic that interests you and dig in! If you don’t know where to start, retrieving indicators is a good place to start.

Hint

When using this documentation, it will be helpful to have a basic understanding of the ThreatConnect Data Model.