Enterprise Edition

Adding new API definitions

• Last updated: July 16, 2024

• Read time: 4 Minutes

Burp Suite Enterprise Edition enables you to upload an OpenAPI definition to run a specific API scan. You can add new API definitions at any time.

API definitions are managed in the Sites menu. Each site can have only one API definition, but you can create unlimited sites to accommodate multiple definitions.

API definition format

Burp Suite Enterprise Edition enables you to provide API definitions as a JSON or YAML file in either OpenAPI 2.0.x or 3.0.x format.

You can add API definitions by either uploading a file or providing a URL. This choice impacts how Burp Suite Enterprise Edition handles authentication and updates.

Authentication

When you upload an API definition file, Burp Suite Enterprise Edition automatically parses it and adds any detected authentication schemes to the Authentication tab. You can then add the necessary credentials.

If you link to the definition with a URL, you need to add both the authentication schemes and their associated credentials in the Authentication tab manually.

Updates

When you upload an API definition file, it is used for every scan until you update it by uploading a new version.

If you link to the definition with a URL, Burp Suite Enterprise Edition uses the latest version of the file each time it scans.

Adding an API definition

To add an API definition:

1. Select Sites > Add a new site to display the Create a new site page.

2. Select API from the Site type panel.

3. Enter a unique Site name.

4. To add the API to an existing folder, select from the Site folder drop-down menu. If you leave this field blank then the API is created at the top level of the site tree.

5. Select how you will provide the API definition. You can either supply a URL or Upload file.

6. If you selected URL, enter the Host URL. This must be a live link to your definition file.

7. If you selected Upload file, click the Upload file button and select the definition file from the dialog. Burp Suite Enterprise Edition parses the file and identifies the authentication schemes used in it.

8. If required, configure optional settings for your API. There are a wide range of available settings, including scan configurations, proxy, and cookie settings. For more information on the settings available, see Configuring site settings.

9. Click Save.

Burp Suite Enterprise Edition adds the new API to the site tree and prompts you to schedule a scan.

Configuring API authentication

You can configure endpoint authentication for API scans. This enables Burp Suite Enterprise Edition to access authenticated endpoints, increasing your scanning coverage.

Burp Suite Enterprise Edition supports Basic, Bearer Token, and API Key authentication. You can manage API authentication via the Authentication tab, which lists schemes from uploaded definitions and manually added credentials.

To add new API credentials:

1. Click Add API credentials to display the Add Authentication dialog.

2. Select the Authentication type and add credentials. All fields are mandatory:

   1. For Basic, enter the Username and Password.

   2. For Bearer Token, enter a Format and the Token.

   3. For API Key, select where the key should be added. The options are Query parameter, Cookie, or Header. Then enter a Name and the Key.

3. Enter a Label. This is a unique identifier for this set of credentials.

4. Click Save to save your changes and close the dialog.

To edit an existing authentication method, click its pencil icon.

To delete an existing authentication method, click its trash icon.

Optional settings for your API

When you add a new API site, you can configure the following additional settings:

• Scan configuration

• Connections

• Headers and cookies

• Extensions

• Scanning pool

• Notifications

For more information on configuring the optional settings for your API, see Configuring site settings.