Introduction

This guide walks you through the complete process of setting up an API target in Astra, from entering your base URL to configuring authentication and verifying ownership. Once set up, Astra's vulnerability scanner can thoroughly assess your API endpoints for security issues.

Pre-requisites (For Pentest/Scan)

Before starting the setup, ensure the following details are available :

• API Base URL
  Share a non-production environment URL (preferably QA or Staging) for testing.

• Definition Files

  Keep the API definition file handy for the upload [ Supported: Postman, Hoppscotch, HAR file]

• Authentication details
  User Credentials/Token for the Authentication if you are using OAuth, JWT, API key, Basic auth etc

Instructions

Step 1: Verify Ownership [For trial Users]

Before configuring your API target, you must verify that you own the domain or application. This ensures only authorized users can initiate scans.

1. Go to the Targets page. Under the Pending Verification section, click Start Verification next to your target.

   

2. Fill in the Application Name, Business Name, and Target URL.

   

3. Select Manual Verification. Astra's support team will verify ownership within 12–24 hours. You will receive an email once approved.

   

Once verified, your target moves from Pending Verification to Pending Setup.

Step 2: Access the Target Setup Wizard

Navigate to the Targets page and click Setup Target. You will be directed to the target setup wizard where you can configure your API target across the following steps.

Step 3: Add Target Identity

Provide the basic details about your application:

• API base URL : Add the the root URL of your API, including the correct protocol (http:// or https://) and full domain name. All endpoint paths are resolved relative to this URL.

• Target Name : Preselected to display name for your API target.

• Business Name: Add your official Business name here as this field will be displayed on your reports and certification.

• Environment : Select staging or production

  📄 Should I run a vulnerability scan on Production or Staging environment?

Step 4: Add API Details

Choose how you want to share your API structure with Astra. This helps build an endpoint inventory for scanning.

• OpenAPI Spec File : upload your exported OpenAPI specification. This allows Astra to classify risks based on your documented endpoints.

• Collection File: upload a Postman/Hoppscotch/HAR Collection file to build an endpoint inventory for DAST scans.

• Traffic Collector : connect a Traffic Collector to automatically discover endpoints from live API traffic.

NOTE: Traffic collector feature will be enabled/disabled depending on your purchased plan

API Definition Files[Required]

Upload the relevant files based on your selection in the previous step:

• Postman/Hoppscotch/HAR Collection file : outlines the requests, endpoints, and workflows your API uses.

• Postman/Hoppscotch/HAR Environment file (if applicable) : configures the testing environment (development, staging, or production).

• OpenAPI Document (optional) :Click "Add OpenAPI spec upload option" to add a OpenAPI file. This provides a detailed map of your API endpoints for more precise scanning.

Step 6: Authentication

Many APIs are secured, and the scanner must authenticate to access your endpoints. Providing the correct authentication method is critical . without it, the scanner will fail to reach protected endpoints.

You can configure authentication either during target setup or later from the API Target Settings page.

Workflow

1. Select an Authentication Type from the dropdown.

2. Fill in the required fields for that type (fields change based on your selection).

3. The authorization header will be automatically generated when scanning your target

Supported Authentication Types

Basic Auth

• Inputs: Username, Password

bash

curl -v -u "username:password" -X POST https://api.example.com/secure

OAuth 2.0 Client Credentials Grant

• Inputs: Access Token URL, Client ID, Client Secret

bash

curl -v -X POST https://auth.example.com/token \  
-d "grant_type=client_credentials" \  
-d "client_id=abc123" \  
-d "client_secret=xyz789"

OAuth 2.0 Password Credentials Grant

• Inputs: Access Token URL, Client ID, Client Secret, Username, Password

bash

curl -v -X POST https://auth.example.com/token \  
-d "grant_type=password" \  
-d "client_id=abc123" \  
-d "client_secret=xyz789" \  
-d "username=john" \  
-d "password=doe"

Bearer Token (Static)

• Inputs: Static token string

bash

curl -v -H "Authorization: Bearer YOUR_TOKEN_HERE" \  -X POST https://api.example.com/resource

JWT Bearer

• Inputs: Algorithm (HS256 or RS256), Secret (base64 encoded), JWT Payload & Header, Header Prefix, Header Name

bash

curl -v -H "Authorization: Bearer <JWT_TOKEN>" \  -X POST https://api.example.com/data

API Key

• Inputs: Header Name (e.g. x-api-key), Header Value (e.g. abc123)

bash

curl -v -H "x-api-key: abc123" \  -X POST https://api.example.com/secure

Step 7: Improve Coverage

Providing context about your application helps Astra improve scan accuracy and assists security engineers during manual testing.

Additional Hosts

Add up to 5 hosts to include in the scan scope.

Custom HTTP headers
Add custom headers that will be attached to every scanner request. Useful for:

• Cloud API gateways that require routing headers (e.g. x-api-key, x-tenant-id)

• WAF/firewall environments that enforce security controls via headers

• Internal services using non-standard header-based authentication

Excluded URLs

Skip endpoints that match these URL fragments during scanning.Define regex patterns for URLs the scanner should skip. Common uses:

• Health and readiness probes (/health, /status, /metrics)

• Static asset endpoints (/assets/.*\.(png|jpg|css|js)$)

• Admin paths that should not be scanned in automated mode

Step 8: Complete Setup

Review all your entries and click Complete Setup to finalize the target configuration. You can either start a scan directly or schedule scan. You can also choose to directly "Activate Target" instead . Once saved, you can initiate a scan to begin testing your API for vulnerabilities.

Note: Any configuration changes made while a scan is in progress will only take effect from the next scan onwards.

For assistance, raise a support ticket from the Astra dashboard.

Troubleshooting

Scanner is not reaching my API endpoints

Symptoms

• Scan completes but reports zero endpoints tested

• Scanner returns authentication errors on all requests

Causes & Fixes

• Incorrect Base URL — confirm the URL includes the correct protocol (http:// or https://) and resolves publicly or from Astra's network. A trailing slash mismatch can also cause routing failures.

• Authentication not saved — verification alone does not persist credentials. Ensure you clicked Save Credential after verifying. Return to API Auth settings to confirm.

• Wrong authentication type selected — verify that the auth type matches what your API actually requires. For example, selecting Bearer Token when the API expects OAuth 2.0 Client Credentials will result in rejected requests.

• Token has expired — static Bearer Tokens and JWT tokens have expiry windows. Regenerate a fresh token and update the credential settings before re-running the scan.

Credential verification is failing

Symptoms

• Clicking Verify Credential returns a non-2xx response

• Verification times out

Causes & Fixes

• Wrong credentials — double-check the values entered. For OAuth 2.0, confirm the Access Token URL is correct and reachable.

• API is behind a firewall or allowlist — if your API restricts inbound traffic by IP, whitelist Astra's scanner IPs. Reach out to support to obtain the current IP range.

• JWT secret not base64 encoded — the JWT Bearer type requires the secret to be base64 encoded. Encoding a plain-text secret and retrying usually resolves this.

• Rate limiting on the token endpoint — if your auth server throttles repeated requests, wait a few minutes before retrying verification.

No endpoints are appearing in the scan results

Symptoms

• Scan runs successfully but the endpoint inventory is empty or incomplete

Causes & Fixes

• Definition file not uploaded — confirm that your Collection or OpenAPI spec was successfully uploaded in the Definition Files step. Re-upload if the file is missing.

• Postman Collection references unresolved environment variables — if your collection uses {{variables}}, make sure the corresponding Postman Environment file was also uploaded.

• Traffic Collector not receiving traffic — if you selected the Traffic Collector method, verify the collector is running and actively receiving live traffic before initiating the scan.

• Endpoints excluded by regex — review your URL Exclusion Regex patterns in Advanced Settings. An overly broad pattern may be inadvertently excluding valid endpoints.

Target is stuck in Pending Verification

Symptoms

• Target has not moved to Pending Setup after 24 hours

Causes & Fixes

• Verification request not submitted correctly — confirm you completed all fields (Application Name, Business Name, Target URL) and selected Manual Verification before submitting.

• Email notification missed — check your spam or junk folder for the approval email from Astra.

• If more than 24 hours have passed, raise a support ticket from the Astra dashboard for a status update.

Best Practices

Verify against a stable environment Run the target setup and credential verification against a staging or pre-production environment that mirrors production closely. Avoid pointing the scanner at a live production API unless you have confirmed it can handle the additional load.

Use short-lived tokens only for verification, not for saved credentials If your API issues short-lived Bearer or JWT tokens, do not use a token that will expire soon as your saved credential. Set up OAuth 2.0 with Client Credentials or Password grant instead — the scanner will automatically fetch fresh tokens before each scan.

Keep your definition files up to date Your Postman Collection or OpenAPI spec defines the endpoint inventory the scanner works from. Re-upload updated files whenever new endpoints are added or existing ones change, to ensure full coverage.

Be specific with URL exclusion patterns Overly broad regex patterns in the URL Exclusion field can silently skip large portions of your API. Test your patterns against a sample URL list before applying them, and document the reason for each exclusion in the Additional Notes field.

Use Extra HTTP Headers for environment routing, not authentication Extra HTTP Headers are best suited for gateway routing headers (x-tenant-id, x-api-key) or WAF bypass headers — not as a substitute for proper authentication configuration. Authentication should always be handled through the API Auth step so credentials can be verified and rotated independently.

Document non-standard configurations in Additional Notes If your API has rate limiting, unusual authentication flows, or endpoints that behave differently under load, record these in the Additional Notes step. This context helps Astra's security engineers interpret scan results accurately and avoid false positives.

Restrict scanner access to non-destructive endpoints where needed If your API includes endpoints that trigger irreversible actions (e.g. sending emails, deleting records, processing payments), use URL Exclusion Regex to exclude them from automated scanning, or flag them explicitly in Additional Notes.