StackHawk API
Your StackHawk Organization must belong to a plan with API Access enabled to use this feature. Reach out to support@stackhawk.com to enable it.
Getting Started
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 accessible to applications and organizations the user belongs to and is permissioned to access.
View the StackHawk API Docs
Authorization
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 Standards
Client Errors
API Calls that fail due to client input will return a 4xx status code.
401 Unauthorized
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 response 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:
| Parameter | Description |
|---|---|
pageToken | A string incrementing count of pages in the pagination, starting from '0' |
pageSize | The number of elements to request in the page, defaults to 10 |
sortField | Sorts the listed resource by an approved field. Defaults to sorting by resource name |
sortDir | Either 'asc' or 'desc', defaults ascending |
The response body of these API routes will additionally include two fields:
| Field | Description |
|---|---|
nextPageToken | A string indicating the next pageToken to pass in for the next page of results with this request |
totalCount | The total number of listed resources the request query can paginate through |
Example Code
We’ve put together a repo with a few example apps in different languages and frameworks to help you get started.
Example API Clients Repo
OpenAPI Specification
The StackHawk API exposes an 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.
Need Help?
If you encounter an issue you cannot solve with this documentation, reach out to StackHawk Support.