Please note that this feature is only available for the Pro and Premium plans and Probely Plus.
This article explains how to scan a standalone API target with Probely.
How does the API scanning work?
To scan an API, we need its specification, the schema. You can define it with an URL pointing to the schema or uploading it to Probely. The former has the advantage of us fetching the schema before every scan, ensuring we always get the most up to date version.
Probely supports APIs with different authentication methods. You can set a fixed API key in a custom header or configure a login endpoint from which you obtain an authentication token.
You can also define custom parameter values that replace those found in the schema. This allows you to override example values or to ensure domain-specific values are properly filled.
How do I scan an API?
Scanning an API is a simple three-step process:
- Add an API target
- Configure the API target
- Start the scan
This article describes these steps in detail, covering multiple authentication scenarios.
1. Adding an API target
For Probely Plus, go to https://plus.probely.app/targets/add to add a target.
Set the URL field to the API base URL, i.e., the domain from which your API is actually serving clients.
Tick the checkbox Is this an API target, and then choose between entering your API schema URL or upload it. We support both JSON and YAML schemas.
Setting the schema URL has the advantage of Probely fetching it before a scan, so we always scan the API's latest version.
Example of how to add an API target
2. Configure an API target
After adding (and verifying, if needed) the target, go to its settings.
API targets have a few different settings when compared with a non API target:
- Target Authentication is replaced with API Target Authentication
- adds API Scanning Settings, where the schema and custom values are set
- no seeds list setting: we only crawl and scan endpoints defined in the schema
- no extra hosts setting: this only makes sense for web applications
Let's go over these settings:
API Target Authentication
Scenario 1: you have a fixed API key that must be placed in all requests, in a header.
This is the simplest scenario, as you only need to add a Custom Header with the appropriate header name, Authorization in this example, and its value.
scenario 1: authenticate with a fixed API key in a header
Scenario 2: you have a fixed API key that must be placed in a specific parameter.
In the API Scanning Settings section, add an API Parameter Custom Value, with the field's name and the respective value. The value should be your API key.
You can add multiple entries if your API key location varies. For instance, if you use
key for GETs and
token for POSTs, add both fields with the same value. Probely will use the right one for each endpoint.
scenario 2: authenticate with a fixed API key in a parameter
Scenario 3: obtain a token from an API endpoint.
In this scenario, you get the API token from an endpoint that authenticates you, for instance, with a pair of credentials, such as username + password.
This authenticating pattern is often found on APIs that support web applications: the user authenticates himself with his username and password, obtaining a token used on all requests thereafter.
scenario 3: use a token obtained from an API endpoint
Go to the API Target Authentication section on the target settings and fill in the appropriate values:
- Authentication Media Type: the content type of the payload/request to the authentication endpoint
- Login URL: the authentication URL
- Authentication Payload: the content to send to the Login URL. The request uses the POST method.
Click Fetch to perform the authentication. If the authentication fails, an error will be displayed. If the authentication succeeds, the Token Field Name will list the fields obtained in the authentication response. Choose the field that contains the authentication token.
Next, at Place Token In, choose where to place the token in the API requests. For most cases, the token is placed in a header. The other available option is cookie.
At Field Name, enter the name of the header or cookie that will hold the token.
Optionally, set a Value Prefix for the token value. This is often needed for JWTs. For instance, if your API requires you to send a header
Authorization: JWT <token>, set the following values:
- Field Name:
without the colon ( : ) separator
- Value Prefix:
note the space in the end so that the JWT and the token are properly separated
API Scanning Settings
Here you can override or set values for the endpoint parameters described in the schema.
Our scanning engine has a set of predetermined values for the most common parameters, such as email, address, and dates.
If we cannot infer the adequate value for a parameter, we use a default value. You can override that behavior by setting specific values, such as
product_id, as shown in the example below:
setting a custom email and product_id
3. Start the scan
Just press Scan Now, and the scan will start in a few seconds. You can follow the scan progress on the scan page.
After the scan ends, you can download a coverage report in CSV format that lists the endpoints parsed from the schema and the respective HTTP response code. The coverage report is a good tool to help you understand if there were endpoints that failed.