Authenticated API Scan

Modern APIs often protect endpoints behind authentication layers like tokens, cookies, or session-based logins. To effectively test these endpoints, ZeroThreat allows you to configure Authenticated API Scans.

Unlike Unauthenticated API Scans, which only target public endpoints, an authenticated scan allows ZeroThreat to interact with and test endpoints that require valid credentials or session tokens. This ensures your critical APIs are also covered in your security testing.

Before proceeding, it’s important to note that API Authentication is configured at the collection level. This means you’ll first need to create a Collection for your API target—where all your API definitions (endpoints) are managed. If your collection is already created, you’re ready to configure authentication and run your first authenticated API scan.

Step 1: Start a New Authenticated API Scan

  1. Go to the ZeroThreat Dashboard and select your API Target.

  2. Ensure an API Collection already exists for this target. If not, refer to the Creating a Collection guide.

  3. Click on “Start New Authenticated API Scan”. This will open the API Scan Configuration Drawer, where you’ll define how ZeroThreat should authenticate against your APIs.

Step 2: Create an API Authentication Configuration

Inside the drawer:

  • Select API Collection Source: Choose the collection you want to configure authentication for.

  • Enter a Name and Description: Provide a short Name (2-6 characters, e.g., UAT01, OAUTH, APIK1) and a meaningful Description for your configuration so you can easily identify it later.

Step 3: Choose Your Authentication Method

ZeroThreat offers three API authentication methods:

Authentication Type
Purpose

Custom Headers

For static tokens, cookies or fixed header-based authentication.

Configure Authentication Request Payload

For dynamic login flows where tokens are generated at runtime and may expire after certain time, making it essential to generate fresh login before each scan to ensure valid authentication (pair with Refresh Token if tokens are short-lived).

Third-Party Login Request

For apps using an 3rd party API's (OAuth 2.0 and others). Configure the token endpoint, request body, and optional headers so ZeroThreat fetches an access token at scan start—no login endpoint from your API collection required (pair with Refresh Token if tokens are short-lived).

Option 1: Custom Headers

If your API uses static tokens or keys:

  • Go with custom headers approach and click on Add Custom headers.

  • Add one or more Header Name / Value pairs and click on Save.

  • These headers will be sent with every API request during the scan.

This is ideal for APIs that don’t require dynamic login but rely on a constant key or token.

Option 2: Configure Authentication Request Payload

For APIs that require a login flow:

  1. Go with Authentication Request Payload approach and click on Add Credentials.

  2. A new drawer will appear showing all available API endpoints from your collection.

Here, select:

  • Login API: The endpoint used for user authentication, where the session starts and tokens are typically generated. If your login request doesn't have any values in the JSON then the dropdown will open and you will need to fill the values required for login. Once done you will be able to select the login endpoint.

  • Logout API: If your API includes a logout endpoint, select it here. If no logout API exists, you can select any placeholder endpoint to proceed.

Note: Skip the next step of Response Property Mapping if your Login API returns authentication token value in Response headers.

Response Property Mapping (Only Required When Token is in Response Body)

In some APIs, the authentication token (such as a Bearer token or session cookies) are returned inside the response body of the login API—rather than in the response headers. In these cases, ZeroThreat needs to know where exactly in the response body the token is located, so it can extract the value and automatically insert it as a header for all subsequent API requests during the scan.

You’ll do this by setting up a Response Property Mapping.

Example Scenario:

{
  "data": {
    "user": {
      "token": "abc123xyz"
    }
  }
}

For this example:

  • Header Name: Authorization

  • Response Property Path: data.user.token

ZeroThreat will parse the JSON body, locate the token at the specified path, and add it to the Authorization header for all future API requests in the scan.

Response Property Mapping is only required if your token is returned in the response body. If your token is already provided in the response headers, ZeroThreat will automatically handle it—no mapping needed.

This mapping step ensures ZeroThreat can successfully authenticate on each API call by dynamically attaching the correct token.

Option 3: Add Third Party Login Request

You can use this method of authentication when your application relies on an external identity provider (OAuth 2.0 or other 3rd party API's) to issue access tokens. Instead of picking a login endpoint from your API collection, you define the token request here. ZeroThreat will run this request before the scan, capture the access token, and attach it to all subsequent API calls.

Configure a Third-Party Login Request

  1. Click on Add Third-Party Login Request in the Authenticated API Scan configuration.

  1. Fill the basic Request details

  • HTTP Method: Usually POST.

  • URL: Your 3rd party token endpoint (e.g., https://zerothreat.example.com/oauth/token).

  • Content type: As required by the endpoint

  1. Configure Payload : Request Body Add the fields your token endpoint expects. Common examples includes login, password, auth_type, grant_type, client_id, scope, code, and more.

  1. Configure Payload : Request Header (optional) You can add additional headers to this token request, if your token endpoint requires them—e.g., Referer, Host, Accept, Content-Type or any other required headers.

  1. Configure Payload : Response Property Mapping with Header (optional) This step is only required if your API sends the generated token in Response body, if it is returned in Response header then you can skip this step. In other cases, you need to map the Response Body token field to Request Headers for all subsequent API Calls. See the Response Property Mapping section for more details.

In the above example, ZeroThreat will take the value of data.user.token and bind it to the value of Authorization header with prefix for all subsequent API calls. This enables that an authenticated API scan with freshly generated token value is used for authenticated API scanning.

  1. Click Save () button to finalize the login setup. ZeroThreat will execute this request at scan start and use the resulting token automatically in all future scans.

Refresh Token (Optional)

Many modern APIs issue short-lived access tokens (e.g., JWTs) with a specific Time-to-Live (TTL) and expect clients to refresh them periodically. When you configure this feature, ZeroThreat will call your refresh endpoint on a schedule you define. It uses the existing, valid token to obtain a new access token and then seamlessly continues the scan without interruption.

This pattern is standard in modern authentication flows, particularly OAuth 2.0, which uses the “refresh_token” grant type. If your API follows a similar rotating-token scheme, this configuration is essential for reliable authenticated scanning.

This is an optional configuration and only required if your API's access tokens have a short lifespan.

How to Configure the Refresh Token Request

After configuring your primary authentication method, you can set up the refresh token flow. The configuration is broken down into basic details and the request payload.

1. Basic Request Details

First, define the core information for your refresh endpoint:

  • Method: The HTTP method used to call the refresh endpoint. This is typically POST.

  • URL: The full URL of your API's token refresh endpoint (e.g., https://api.yourapp.com/api/refreshtoken).

  • Content type: The format of the data being sent in the request body, application/json or application/x-www-form-urlencoded

  • Refresh Interval (Min): How often ZeroThreat should request a new token.

2. Configure Payload

This section defines the Request body, Request Headers, and Response mapping with Header.

  • Tab 1 (Request Body) Use this to build the JSON payload for the refresh request. You often need to send the current refresh token to get a new access token.

    • Property Name: The key in the JSON object (e.g., grant_type, scope, client_id).

    • Property Value: The value for that key (e.g., refresh_token).

  • Tab 2 (Request Header) Use this optional tab if your refresh endpoint requires specific HTTP headers to be added to the Request. For instance, your API might require a static, secret API key or some other compulsory Header for all refresh attempts.

    • Header Name: The name of the HTTP header (e.g., X-API-Key, X-API-Version) .

    • Header Value: The value for the header (e.g., your-static-api-key-value, 2.41-alpha).

  • Tab 3 (Response Property Mapping with Header) This configuration is only required if your API returns the new access token within the JSON response body. If your API sends the new token back in a response header (e.g., in a Set-Cookie header), ZeroThreat handles it automatically and you can skip this tab.

    When the token is in the response body, you must use this tab to map its location. This tells ZeroThreat how to extract the token from response and apply it as a request header for all subsequent API calls, keeping the session authenticated.

    • Header Name: The header where the new token should be placed for all subsequent scan requests (e.g., Authorization).

    • Header Value Prefix: An optional prefix added before the token. For Bearer tokens, you would enter Bearer

    • Response Property Path: The dot-notation path to the new token within the JSON response body. In the example, the path to abc123xyz is data.user.token. So the value abc123xyz (with prefix bearer) will be used as Authorization header value for all subsequent requests.

Once configured, click Save. ZeroThreat will now automatically keep the session alive during authenticated API scans.

Step 4: Save and Start the Scan

Once your authentication setup is complete:

  • Click “Save Configuration & Exit” if you want to save the config for later use.

  • Or choose “Save & Start Scan” to immediately launch the authenticated API scan.

You can monitor the scan progress from the Scans section and review detailed results in your Scan Report once the scan finishes.

Next Step? Learn how to Interpret Scan Results and analyze vulnerabilities found in your API endpoints in Scan Report guide.

PreviousUnauthenticated API ScanNextScan Results

Last updated