StackHawk API Documentation
Your StackHawk Organization must belong to a plan with API Access enabled to use this feature. Reach out to email@example.com to enable it.
Use of the StackHawk API will require a StackHawk account. Requests made to the StackHawk API are associated with the calling user, and API resources are only accesible to applications and organizations the user belongs to and is permissioned to access.
To make authorized requests to the StackHawk API, you will first use your API Key from the StackHawk platform. From the StackHawk platform, under Settings > API Keys create a new API Key. These secrets are long-lived, so store this value in a secure fashion. That will be used to request an access token, which is used with the
Authorization: Bearer header to authorize your requests made to the StackHawk API.
To get an access token, make a request to
GET /api/v1/auth/login and provide the user API Key through the
X-ApiKey request header. This route will then return an access token that can authenticate further API requests. This token can then be used to authenticate subsequent requests, using the
Authorization: Bearer header.
API Calls that fail due to client input will return a 4xx status code.
The server doesn’t think you should be making this request.
This error is intentionally vague for security purposes, but any of the following may cause it:
- no authentication was provided
- authentication has expired
- authentication is insufficient for the requested resource
400 Bad Request
The server could not process this request, although it may have tried.
The JSON reponse body
message may include details on what input was specifically invalid.
404 Not Found
The route or resource does not exist.
429 Too Many Requests
The StackHawk API is ratelimited with a sliding window. At most 180 API requests are allowed per minute. This error status is returned when the ratelimiting threshold has been reached.
Pagination and Sorting
Listing API routes will return resources in a paginated fashion. Paginated requests follow a pattern of taking the following optional path parameters:
pageToken: a string incrementing count of pages in the pagination, starting from
pageSize: the number of elements to request in the page, defaults to
sortField: sorts the listed resource by an approved field. defaults to sorting by resource
'desc', defaults ascending
The responseBody of these API routes will additionally include two fields:
nextPageToken: a string indicating the next
pageTokento pass in for the next page of results with this request
totalCount: the total number of listed resources the request query can paginate through
We’ve put together a repo with a few example apps in different languages and frameworks to help you get started.
The StackHawk API exposes a OpenAPI specification file that can be referenced for automation or research purposes. The latest published spec for the StackHawk Public API can be found here.
Questions? Comments? Concerns? Kaa-Kaww?
We are always making advancements and improvements to our Platform, Scanner and the StackHawk API. If you encounter an issue you cannot solve with this documentation, please reach out to StackHawk Support with your questions. We will help you troubleshoot any issues and get you soaring with StackHawk.