# Web API scans

> Scanning an API from its OpenAPI specification.

Source: https://scansuite.eu/documentation/usage/web-app-scanning/web-api-scans
Last reviewed: 2026-10-19

**API Scan** tests a web API from its OpenAPI specification: it reads the routes and parameters the specification describes and attacks them with ZAP and Wapiti. It runs from the Dynamic Analysis page like any web scan; see [Web App Scanning](https://scansuite.eu/documentation/usage/web-app-scanning) for the form.

## Before you start

| You need | How to check |
|---|---|
| An OpenAPI specification served by the API itself | Open the specification URL in a browser or with curl -fsS <SPEC_URL>: it must return the JSON or YAML document. |
| The API host allowed for your team | Teams, Scanning tab, Web targets card, Check whether targets are allowed: the specification URL must be reported as allowed. |
| A product | It is listed under Product / Eng ID on the form. |

## Run an API scan

1. **Open the form**

   Web App Scanning in the sidebar (the Dynamic Analysis page).
2. **Enter the specification URL**

   In Specify the URLs, the address of the OpenAPI document itself, for example https://api.example.com/openapi.json, not the API root.
3. **Switch off Autonomous AI assessment**

   It is on by default and, while on, the AI Pentest agent decides what runs instead of API Scan.
4. **Switch on API Scan**

   Open the collapsed Specialized & API Scanning group under DAST Engine Settings and switch on API Scan.
5. **Add authentication**

   Cookies (optional) or Custom header (optional), as the API expects them, see below.
6. **Select Start Analysis**

   Scan submitted appears and the scan's page opens.

![ScanSuite API scan configuration](https://scansuite.eu/static/assets/img/docs/usage/web-app-scanning/web-api-scans/01.png)

*Configuring an API scan*

**Check that it worked:** the scan ends Finished on its page. Its findings are in the **Report** and, at Medium severity and above, on the Vulnerabilities page (with the team's **Store scanner findings** on, the default).

## What the specification must look like

|  | Rule |
|---|---|
| Format | OpenAPI (JSON or YAML). |
| Address | Only letters, digits and : . _ / - are accepted, so a specification URL with a query string, such as …/openapi?format=json, is refused. Serve it at a plain path. See Targets on Web App Scanning. |
| Host | The API is tested on the scheme and host of the specification URL, so the specification should be served by the API's own host. |
| Authentication | If fetching the specification needs a header or cookie, give it: the same values are used for the specification and the API calls. |
| TLS | Wapiti checks the certificate; with a self-signed certificate its part of the scan may find nothing. |
| Duration | The ZAP part stops after about two hours. URLs containing logout are not called, so the session is not ended. |

## Authentication

API Scan uses the **Cookies** and the **Custom header** from the form, so the authenticated API surface is tested rather than skipped. Any header works, not only Authorization. Wapiti sends all of them; ZAP sends one value: the first header, or the cookies when no header is set. Put the credential that matters most first.

## From a pipeline or a terminal

```bash
scansuite-ci --scan-type dast --scanners api_scan \
  --target https://api.example.com/openapi.json --header "Authorization: Bearer $API_TOKEN"
```

See [CI/CD and automation](https://scansuite.eu/documentation/reference/cicd).