StackHawk API Documentation

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 accesible 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 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 '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 responseBody of these API routes will additionally include two fields:

• 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 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.