How to use the Crashtest Security API

This article shows you how to set up and use the public API to automate creating projects and scans.

TL;DR

• Need an API Key? Request at support@crashtest-security.com
• Detailed OpenAPI Documentation: https://docs.crashtest.cloud

Why should I use the API?

The API grants access to multiple features of the Crashtest Security Suite without human interaction, like clicking through the interface. For example, systems that need to update data dynamically can set up projects and start scans. 

What do I need to use the API?

To get started using the API, an API Key is required. Every key is unique for a single user and allows them to interact with their stored data in the Crashtest Security Suite.

An API Key can be requested by sending an email to support@crashtest-security.com.

Once the key has been assigned, it must be attached to every request sent to the API. 

Where do I have to attach the API Key?

There are multiple ways of attaching the key. It can either be attached to the URL as a parameter or used as a header field within the request. Both versions allow the "api_key" attribute to be either fully lower or upper case.

As a parameter in the URL:

• api.crashtest.cloud/something?API_KEY=my_secret_key
• api.crashtest.cloud/something?api_key=my_secret_key

As a header attribute:

• API_KEY: my_secret_key
• api_key: my_secret_key

What can I do using the API?

The API is based on the Rest API format and allows sending GET, POST, and DELETE requests. All available operations with detailed specifications can be found here. As the API Key is assigned to the user, it can modify all teams of which the user is a member.

Note: The same restrictions and permissions the user normally has, are also applied for the API.

For most requests, it is necessary to have some IDs in advance. An ID is a unique identifier that clarifies which team and project... should be updated.

Team ID

The team ID can be retrieved from the Local Storage of the Browser or by requesting the information at support@crashtest-security.com.

The Local Storage can be found by opening the browser's developer tools. 

1. Click on the "Application" tab.
2. Select the local storage for "https://crashtest.cloud"
3. Check the "user" entry for the "active_team_id"

This value will update and represent the newly selected team when switching between different teams.

Project ID

There are two ways of retrieving the ID of a project.

1. If the project is created using the API, the response of the "create API" call contains the project's ID.
   
   
2. The project ID can be found by clicking on the User Interface on a single project. Afterward, the URL in the browser shows a URL like: https://crashtest.cloud/projects/123.
   The "123" at the end is, in this case, the ID of the specific project.

Scan ID

When starting a scan using the API, the response of the call contains the ID of the scan:

If the API call to start a new scan is used while another scan for the same project is already running, the API call returns the ID of the running scan.

Operations

Currently, the API offers the following operations:

• Projects
  • Create a new project
  • Delete a project
• Scans
  • Start a new scan for a project
  • Stop a running Scan
  • Retrieve the status of a scan
  • Retrieve the finding for a scan (PDF, XML, JSON)