API Keys

  • API keys are tied to accounts with access to the Admin Portal (User account). To retrieve an API key, log into your Admin Portal account, and click on the API Keys menu entry.
  • Use an existing key or click the Add API Key button to create a new one.

Security model

  • API keys are tied to the Organization in which it was generated. API Keys are not tied to individual users.

  • Keep API keys secure. Any person in possesion of an API key could potentially gain access to the data of the account associated with the key.

  • API Keys can be configured to grant access to individual services, as well as in a write or read-only capacity. Ensure that the key you are using has the required permission to access the services that you are using. The Read permission only allows GET requests, while the Write permissions grants access to the POST, PATCH, PUT and DELETE methods.

  • API Keys can be set to expire. Keys that have expired will be rejected by the API server.

  • API keys can be restricted to one or multiple subnets. In the eventuality that our API key is stolen, a person in possession of the API key would not be able to use it.

CORS

  • Optionally, you can list origins for CORS. Set the list of origins as a comma-separated list, e.g. htttps://www.mydomain.com, https://sub.mydomain.com ; leave empty if CORS support isn’t needed for this token.
  • For the Origin to be accepted by the server, the client must provide the Token in the Pre-flight request (see withCredentials in the example)
  • Each origin must include the protocol
  • Be careful not to expose your token to untrusted users.

CORS Example

Using jQuery:

var url = 'https://rest.threatstop.com/v4.0/<service>';
var token = '<your API token>';
$.ajax({
  url: url,
  type: "GET",
  crossDomain: true,
  headers: {'Authorization': 'Bearer ' + token },
  xhrFields: { withCredentials: true },
  dataType: "json",
  success: function (response) {
    console.log("success", response);
  },
  error: function (xhr, status) {
    console.log("error", xhr);
  }
});

API Key sharing

Sharing an API Key with the Share Key feature of the Admin Portal provides a mechanism to pass a key to another ThreatSTOP user, without resorting to sending the API key over an out-of-band system, such as email or chat applications.

Sharing a key doesn’t alter the permissions associated with the key. The key remains valid only for the customer account in which it was created.

Unsharing a key doesn’t invalidate the key, or remove access from the user it was shared with. To invalidate a key after it has been shared, it must be deleted using the Delete Key button on the list of API keys displayed in the Admin Portal.

Authentication

Authentication is performed by providing an API key using the Authorization HTTP header. The format is:

Authorization: Bearer API_KEY

Requests without the Authorization header or with an incorrect API Key will return HTTP/401.

Resource format

Collections are accessed as https://partner-api.threatstop.com/sms/collection_name, while objects are accessed as https://partner-api.threatstop.com/collection_name/{id}.

:id is a generally a UUID.

Operations

The API operations use HTTP methods as follows:

Method Collection Object
GET Retrieve collection listing Retrieve single object
POST Create new object in collection Not applicable
PATCH Not applicable Update one or several object settings
PUT Not applicable Replace an object
DELETE Not available Delete the object

Headers

For requests that create (POST) or update (PATCH, PUT) an object, the data must be provided as a JSON object in the request body and the request must set a Content-Type: application/json header.

This header should not be included for requests that read (GET) an object and don’t include a request body.

API Responses

Status codes

The API returns the following HTTP codes:

Code Description
200 Successful request
201 Successfully created object
400 Error in request
401 Authentication not provided or incorrect
404 API key doesn’t provide access to this service/resource or it does not exist
500 Server side error

JSON objects

Objects are returned as JSON objects. The API outputs a header Content-Type: application/json.

For easier parsing, responses always contain an array, even if a single object is returned. The array is named _data and reachable as ._data[]. If the API response contains a single object, it is reachable as ._data[0].

Data types

Element Format Example
Booleans Case sensitive true, false
Country codes ISO 3166-1 List
Dates ISO-8601, UTC time zone 2018-01-01T20:30:45+00:00
UUID UUID4 format df1b1f2f-acf8-43eb-a3ff-ccb38e954acb

HATEOAS

Every request and every object output by the API contains a HATEOAS object to easily retrieve associated resources. For example, the Device service will return the policy associated with the device. The policy object will contain a link to the policy service for that object.

The object is named _links. It contains an object type and a link (href), e.g.:

{ 
  "_links": {
    "policy": { 
      "href": "https://rest.threatstop.com/v4.0/policies/df11dc61-e54f-4fe2-9f19-08d1d8970861"
    }
  }
}

Pagination

The output of some commands is paginated.

Pagination can be controlled with:

  • limit: the number of records to return; 20 is the default
  • offset: the first record returned in the response

When pagination is possible, the API response will contain a HATEOAS section called ._links. The section contains links to the current page (._links.self), to the previous page (_links.prev) and to the next page (._links.next) as applicable.

Error handling

Error responses (4xx codes) contain an extended error code, to help diagnose the cause of the error. The extended error contains the HTTP status (status_code), a general description (error_description), and when applicable, additional details (additional_info.error_code and additional_info.detail)

{
    "status_code": 400,
    "error_description": "Invalid argument",
    "additional_info": {
        "detail": "Invalid start date",
        "error_code": 10302
    }
}

Metadata

API responses contain a metadata section - see the documentation of the different services for its content.

Every API response will contain a request ID (._meta.request_id) which can be provided to ThreatSTOP support for troubleshooting purposes.