Access the API Change Log here.

Hawk is a protocol that implements hash message authentication code (HMAC) signing based on the API key provided. Hawk was designed to allow two parties to verify the sender of a message by a signed header in the HTTP request. If there is a body to the request, such as sending data via the API, you can verify the integrity of the body as well.

To get started with Hawk:

1. Get necessary environment variables from the Threat Stack platform
2. Try out a Threat Stack framework implementation to help get started with Authentication
3. Use the API v2 Endpoints!

Step 1

Before you can use the Threat Stack API v2, you must authenticate using the 3 environment variables:

• API key
• Organization ID
• User ID

You can find the API key and the IDs on the Application Keys tab within the Settings page.

Step 2

Threat Stack has implemented supported HAWK starter clients for Java, NodeJs, and Python for you to use!

You can clone them from the Threat Stack Github repo.

With your credentials from step 1, you should be able to make a test request to our API which will confirm that you have Hawk set up correctly.

Step 3

After you successfully authentication, you can start using the available API endpoints!

Additional Information

For more details on our Hawk implementations, review one of the following frameworks:

• Go
• Java
• NodeJS
• Python

Some of the API endpoints return data that spans across a wide time range. To help refine the responses, you can specify the time ranges by modifying the from and until parameters. Additionally, all date and time parameters follow ISO-8601 standards.

The API uses UTC timestamps:

Date, Time, Date and Time	Format	Example
Date	yyyy-mm-dd	2008-09-15
Combined date and time (hours)	yyyy-mm-ddThh	2008-09-15T15
Combined date and time (minutes)	yyyy-mm-ddThh:mm	2008-09-15T15:53
Combined date and time (seconds)	yyyy-mm-ddThh:mm:ss	2008-09-15T15:53:00

To return resources created after a specific date, use the from parameter:

https://api.threatstack.com/v2/alerts?from=2017-08-01

To return resources created before a specific date, use the until parameter:

https://api.threatstack.com/v2/alerts?until=2017-02-01

To return resources created within a window of time bounded by specific dates, use the from and until parameters together:

https://api.threatstack.com/v2/alerts?from=2017-01-01&until=2017-04-01

The Alert, Agent, and Vulnerabilities endpoints paginate and return up to 100 records per query. Use the token value from the response to query for the next page. When the token value is null in the response, you have reached the end of the results list.

Example

The token value can be found at the bottom of the response body:

    ],
    "token": "NTk4OGM5MWRmNDUyYWUzZjIzYTk2NWQzLDIwMTctMDgtMDdUMjA6MTA6=="
}

Use this token as an addendum to the query parameter to access the next page:

https://api.threatstack.com/v2/agents?token=NTk4OGM5MWRmNDUyYWUzZjIzYTk2NWQzLDIwMTctMDgtMDdUMjA6MTA6==

NOTE:

Each page of results must display before fetching the next page of results.

Threat Stack has two types of rate limiting: by organization and by IP address.

The rate limit for an organization is 200 requests per minute. Specifically this describes the organization-Id rate limit. This results in an HTTP 429 error message. You can send the next request after 1 minute.

Working Within the Rate Limit

The Threat Stack API includes HTTP headers on every API response. These headers help you determine how much of your organization's rate limit budget has been used.

• x-rate-limit-limit: This parameter displays the maximum number of requests your organization can make in a one minute time window
• x-rate-limit-remaining: This parameter displays the number of requests you have remaining in the time window.
• x-rate-limit-reset: If the rate limit triggers, then this parameter displays the number of milliseconds to wait before sending more requests. If the rate limit is not triggered, then this parameter displays 0.

If the number of requests from an IP address exceeds 1,000 requests per minute, that results in an HTTP 429 error message and a 15 minute lock out for that IP address.