StackHawk API

This is the API specification for the StackHawk REST API, affectionately known as Falcon 🦅 #Kaakaww!

StackHawk is an application security testing tool built for developers. With powerful automation and integration capabilities, StackHawk gives engineers the ability to find and fix security vulnerabilities on every merge.

📘

StackHawk API Access is an Enterprise feature

API Access is available to organizations trialing StackHawk, and is available as part of the Enterprise Plan. Reach out to [email protected] to enable it for your organization.

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 permitted to access.

To make requests to the StackHawk API, you will first need an API Key from the StackHawk platform. That will be used to request an access token, which is used to authorize requests made to the StackHawk API.

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.

Authorization

Requests made to the StackHawk API server are authorized following the OAuth2.0 protocol, and uses json web tokens to authenticate requests.

To get the JWT bearer access token, make a request to GET /api/v1/auth/login and provide your API Key through the X-ApiKey request header. This route will then return the JWT access token that can authenticate further API requests. The access token can then be used to authenticate subsequent API requests, using the authorization: Bearer header.

The access token has a 30-minute expiration, and can be refreshed with the GET /api/v1/auth/refresh-token endpoint.

📘

Learn more!

Exchanging an API Key for an access token to make API requests may seem like an extra step, however this authentication process is following a secure industry practices.

OAuth 2.0 is the industry-standard protocol for authorization of web frameworks, as specified in RFC-6749. JSON Web Tokens are the industry standard method for representing claims access between parties, as specified in RFC-7519

Think of the StackHawk API Key as an id card. It is assigned specific for a single user, and lives until it is revoked. There is only one place in the UI to manually get and replace them, and should be treated securely as a long-lived secret. Put the API Key somewhere safe, and do not expose it in plaintext over the network.

Think of the JWT bearer access token as a wristband to the club. It is temporary, replaceable, automate-able, and contains enough information for an API to authenticate HTTP requests on behalf of the assigned user with the token itself. Losing or exposing the access token is less of a concern, but nonetheless it is still a credential and should be treated securely.

OpenAPI Specification

StackHawk provides the 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 [email protected] with your questions, and we’ll help you troubleshoot any issues and get you soaring with StackHawk.