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.