Enterprise Edition

Adding new API definitions

• Last updated: August 27, 2024

• Read time: 5 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. If you upload a file, you can view API endpoints in the Endpoints tab and authentication methods in the Authentication tab. This choice also 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 a method to provide the API definition:

   • For Host URL, provide a live link to your definition file in the Host URL field.

   • For Upload file, click Upload file and select the definition file from the dialog. Burp Suite Enterprise Edition parses the file and identifies its authentication schemes.

6. 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.

7. 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.

Viewing and configuring endpoints

If you uploaded your API definition as a local file you can view details of its endpoints in the Endpoints tab. Endpoints are automatically populated from your API definition when you upload the file.

The Endpoints tab contains the following information:

• Method - The HTTP method used by the endpoint.

• Host - The protocol and server hostname.

• Path and query - The URL file path and query string.

• Content type - The format of the data that will be sent to the API server.

By default, all endpoints are selected for scanning. Use the checkbox to remove an endpoint from scans of the site.

Filtering endpoints

You can filter which endpoints you see on the Endpoints tab:

• To filter by HTTP method - Use the filter buttons.

• To filter by a specific term - Enter your search term in the Search for an endpoint field, and click the search icon.

After filtering the table, click the top checkbox to select or deselect all filtered endpoints.

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.