REST API

The built-in REST API interface provides you with a way to visualize RESTful web services. The API documentation is built using Swagger, where you can test API operations and instantly view the results to help you scan your applications faster.

Before you begin

Note: Request rate limit: You can make up to 500 requests per minute from each unique IP address. If you go over this limit, AppScan will show a 403 status code and a response specific to your browser.
Important: REST API v4 Now Available!

We're thrilled to announce the release of REST API version 4, bringing you improved performance and enhanced features. This API serves as a vital tool for users employing automation scripts to execute diverse tasks on AppScan on Cloud.

Key Points:

  1. Transition Period: The current version, v2, will remain functional for the next few months. However, we encourage users to proactively update their scripts to leverage the new and improved capabilities of API v4.

  2. Migration Assistance:To facilitate a seamless transition to the updated API, refer to the technical overview provided. It includes essential information and guidance to ensure a smooth migration process.

  3. API v2 availability:API v2 will remain available until July 30, 2024. This extended availability is intended to provide users with ample time to migrate to API v4. If you are using the API through automation scripts, please ensure that a migration plan is in place to avoid disruptions after the specified date.

About this task

Learn how to use the interactive framework by following this example to import an application inventory by using the /api/v4/Apps/ImportFile REST API.

Procedure

  1. Go to your Swagger page and bookmark it for future reference:
  2. Log in to Swagger with your HCL ID.
    1. Expand the Account API and click POST api/v4/Account/ApiKeyLogin to expand the operation details.
      POST API displaying login with API key
    2. Replace the "string" parameters with your Api Key Id and Api Key Secret. Keep the quotation marks.
    3. Click Execute.
    4. Copy the "Token" value from the Response Body.Response body displaying the token
    5. Paste it into the Access token field at the top of the Swagger interface.
      From now on the token is applied automatically to all API calls.
  3. Create an asset group:
    1. Expand the Asset Groups API and click POST /api/v4/AssetGroups.
    2. Replace the "string" parameters with a name and description for the asset group. Keep the quotation marks. Creating an Asset Group API
    3. Click Execute.
    4. Make note of the ID in the Response Body section; you'll need to use that ID in the next API.
      Copy ID from response body
  4. Import an application inventory file:
    1. Expand the Applications API and click POST /api/v4/Apps/ImportFile.
      In the Implementation section, there is a sample file that you can download to get a sense of the types of attributes to include in your file.
    2. Enter the assetGroupId from step 3d in the Value field of the Parameters section.
    3. Click Browse in the uploadedFile section to locate your CSV file of applications to import.
    4. Click Execute.
      A successful import appears as follows:Successful application import

Example

Importing scan files, including the results using REST API
You can import a scan file, including the results, without running the scan in AppScan on Cloud by following these steps:
  1. Make sure you are logged in to Swagger using the API: api/v4/Account/ApiKeyLogin.
  2. Upload the scan file using the API: api/v4/FileUpload and save the FileId for later. For example,

    "FileId": "274bd3a7-a231-41d0-80f6-d22d684af50d"

  3. Expand the Scans API and click POST /api/v4/Scans/Dast. Update the following parameters to generate only the reports without running the scan.
    1. ScanOrTemplateFileId:: Update the FileId you copied in step 2.

      "ScanOrTemplateFileId": "274bd3a7-a231-41d0-80f6-d22d684af50d"

    2. TestOperation: Set this to ReportOnly

      "TestOperation": "ReportOnly"

    Note: Make sure you have mapped the AppID, ScanName, and other required parameters to run the API POST /api/v4/Scans/Dast.

Authenticate using a direct API Key

Authenticate API requests by sending your API Key ID and Secret in a custom HTTP header. The Direct API Key method skips exchanging your key for a session token. This simplifies automation scripts and CI/CD integrations because you no longer need to manage token lifecycles or expiration. Key benefits include:

  • Simplified automation: No need to write logic for "Login," "Get Token," or "Refresh Token."
  • Stateless-like experience: Send the key with every request; the system manages the session in the background.
  • Reduced complexity: Ideal for simple scripts, one-off tasks, or integrations where maintaining session state is difficult.

Technical specification:

To use this feature, include the following header in your HTTP requests:

  • Header name: X-Api-Key
  • Header value format: The value must consist of your Key ID and Key Secret separated by a colon (:). KeyID:KeySecret
  • Example: If your credentials are:
    • Key ID: b0977ee5-c9df-0c8a-5909-184c690cbfa5
    • Key Secret: UnKUn7HupAX9MFviJqYHRy6w7Fk50anSlheQJxQhTiux
      The header should look like this: 
      X-Api-Key: b0977ee5-c9df-0c8a-5909-184c690cbfa5:UnKUn7HupAX9MFviJqYHRy6w7Fk50anSlheQJxQhTiux
Implementation examples:
  1. cURL 
    curl -X GET "https://cloud.appscan.com/api/v4/Scans" \
                                    -H "Accept: application/json" \
                                    -H "X-Api-Key: <Your_Key_ID>:<Your_Key_Secret>"
  2. Python (Requests library)
    import requests
                                        
                                        url = "https://cloud.appscan.com/api/v4/Scans"
                                        key_id = "your_key_id"
                                        key_secret = "your_key_secret"
                                        
                                        # Construct the header value
                                        header_value = f"{key_id}:{key_secret}"
                                        
                                        headers = {
                                        "Accept": "application/json",
                                        "X-Api-Key": header_value
                                        }
                                        
                                        response = requests.get(url, headers=headers)
                                        
                                        if response.status_code == 200:
                                        print("Success:", response.json())
                                        else:
                                        print("Error:", response.status_code, response.text)
Security & behavior notes:

  • Expiration & refresh: The system maintains a 30-minute session for performance, but you do not need to track it. If the session expires, your key is revalidated and a new session is created automatically.

  • Revocation: If you delete your API Key in the AppScan portal, access is immediately revoked. Any active sessions using that key are terminated, and subsequent requests return 401 Unauthorized.

  • Permissions: Requests authenticated with this method inherit the same permissions as the user account that owns the API Key.

Troubleshooting:

  • 401 Unauthorized: Verify that your Key ID and Secret are correct and that the key has not been revoked or deleted.

  • Format error: Make sure there are no spaces between the Key ID, the colon, and the Key Secret (for example, ID:Secret, not ID : Secret).