--- title: API discovery and configuration description: The API Behavioral Security (ABS) AI Engine works in tandem with API Security Enforcer (ASE) to automatically discover new and unknown application programming interface (API)s in your ecosystem. component: pingintelligence version: 5.2 page_id: pingintelligence:managing_pingintelligence_for_apis:pingintelligence_api_discovery_configuration canonical_url: https://docs.pingidentity.com/pingintelligence/5.2/managing_pingintelligence_for_apis/pingintelligence_api_discovery_configuration.html revdate: May 6, 2024 section_ids: configuring-api-discovery: Configuring API discovery about-this-task: About this task steps: Steps configuring-ase-for-api-discovery: Configuring ASE for API discovery about-this-task-2: About this task steps-2: Steps example: Example: --- # API discovery and configuration The API Behavioral Security (ABS) AI Engine works in tandem with API Security Enforcer (ASE) to automatically discover new and unknown application programming interface (API) *(tooltip: \
\

A specification of interactions available for building software to access an application or service.\

\
)*s in your ecosystem. You can view the discovered APIs by using the [ABS discovery REST API](pingintelligence_abs_discovery_api.html). You can also add the discovered APIs to ASE by using API Discovery in the PingIntelligence for APIs Dashboard. For more information, see [Discovered APIs](pingintelligence_discovered_apis.html). ## Configuring API discovery ### About this task To configure API discovery in your environment: ### Steps 1. Enable ABS in ASE. 2. Define `root` API JavaScript Object Notation (JSON) *(tooltip: \
\

An open, lightweight data-interchange format that uses human-readable text to store and transmit data.\

\
)* in ASE. | | | | - | ----------------------------------------------------- | | | ABS discovers APIs only for a `root` API JSON in ASE. | 3. Optionally, configure OAuth token and API Key parameters in `root` API JSON. 4. Configure discovery related parameters using [Global configuration update REST API](../pingintelligence_reference_guide/pingintelligence_global_configuration_update_rest_api.html). | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Use the `update.sh` script to edit the default values related to API discovery. For more information on update script, see [Managing discovery intervals](pingintelligence_managing_discovery_intervals.html). | ## Configuring ASE for API discovery ### About this task The following table summarizes the variables related to API discovery that you need to configure. **API discovery variables** | Variable | Description | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `api_discovery` | Set this variable to **true** to switch on API discovery. To switch off API discovery, set it to **false**. The default value is **true**. | | `discovery_initial_period` | The initial time in hours during which APIs are discovered in your API ecosystem. The default and minimum value is 1-hour. | | `discovery_update_interval` | The time interval in hours at which any new discovered APIs are reported. The default and minimum value is 1-hour. | | `discovery_subpath` | The number of sub-paths that is discovered in an API. The minimum value is 1 and maximum value is 6. For more information, see [Discovery sub-paths](pingintelligence_discovery_subpaths.html). | | `url_limit` | Defines the maximum number of URLs that are reported in a discovered API. | To configure ASE for API discovery: ### Steps * Enable ABS in ASE by running the `enable_abs` command in ASE: ``` ./bin/cli.sh -u admin -p admin enable_abs ABS is now enabled ``` * To verify, run the `status` command in ASE: ``` ./bin/cli.sh status API Security Enforcer status : started mode : sideband http/ws : port 80 https/wss : port 443 firewall : enabled abs : enabled, ssl: enabled abs attack : disabled audit : enabled sideband authentication : disabled ase detected attack : disabled attack list memory : configured 128.00 MB, used 25.60 MB, free 102.40 MB google pubsub : disabled ``` * To configure root API in ASE, define `root` API in ASE. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | If you have configured other APIs in ASE along with the `root` API, ABS monitors traffic only on the root API for the discovery process. A `root` API in ASE is an API for which the API JSON file has `url` as `"/"` and `hostname` as `"*"`.If API discovery is enabled in ABS without `root` API in ASE and you run the `discovery` REST API, it displays an error message: `root API not configured in ASE. To discover APIs configure root API in ASE`. | #### Example: The following is a snippet of `root` API JSON: ```json { "api_metadata": { "protocol": "http", "url": "/", "hostname": "*", "cookie": "", "oauth2_access_token": false, "apikey_qs": "", "apikey_header": "", "enable_blocking": false, "cookie_idle_timeout": "200m", "logout_api_enabled": false, "cookie_persistence_enabled": false, "login_url": "", "api_mapping": { "internal_url": "" }, ``` | | | | - | ------------------------------------------------------------------------------- | | | A sample `root` API ships with ASE in `/pingidentity/ase/config/api` directory. | * Configure API JSON by configuring the settings for `cookie`, `oauth2_access_token`, `apikey_qs`, or `apikey_header` in the `root` API JSON file in ASE. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | API discovery process discovers these parameters in an API only when you set these in the root API. API discovery reports these attributes of an API only when it receives at least 50% of traffic having these attributes. For example, if the root API receives 100 requests and 51 requests have OAuth token, then the OAuth token is reported in the discovered API. Similarly, if the same traffic has less than 50% traffic for API keys or cookies, then they are not reported in the discovered API. | * Configure API discovery in ABS by setting the `api_discovery` parameter to `true` using [Global configuration update REST API](../pingintelligence_reference_guide/pingintelligence_global_configuration_update_rest_api.html). | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you want update the values on an already running system, use the `update.sh` script. For more information on the update script, see [Managing discovery intervals](pingintelligence_managing_discovery_intervals.html). |