--- title: Defining an API using API JSON configuration file in sideband mode description: To secure your API environment using sideband ASE deployment, APIs need to be configured in ASE using an API JSON file. Each API has a unique API JSON file. ASE ships with sample JSON files located in the /config/api directory. You can manually configure the JSON file with the required parameters as shown in the next section. component: pingintelligence version: 5.1 page_id: pingintelligence:api_security_enforcer:pingintelligence_define_api_json_file_sideband canonical_url: https://docs.pingidentity.com/pingintelligence/5.1/api_security_enforcer/pingintelligence_define_api_json_file_sideband.html revdate: April 26, 2024 section_ids: manually-add-api-json-to-ase: Manually add API JSON to ASE update-a-configured-api-json: Update a configured API JSON --- # Defining an API using API JSON configuration file in sideband mode To secure your API environment using sideband ASE deployment, APIs need to be configured in ASE using an API JSON file. Each API has a unique API JSON file. ASE ships with sample JSON files located in the `/config/api` directory. You can manually configure the JSON file with the required parameters as shown in the next section. The API JSON file parameters define the behavior and properties of your API. The sample API JSON files shipped with ASE can be changed to your environment settings and are populated with default values. The following table describes the JSON file parameters: | **Parameter** | **Description** | | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `protocol` | API request type with supported values of:`http` - HTTP | | `url` | The value of the URL for the managed API. You can configure up to 10 levels of sub-paths when ASE is deployed in sideband mode. For example,`"/shopping"-` name of a 1 level API`"/shopping/electronics/phones/brand" –` 4 level API`"/" –` entire server (used for ABS API Discovery or load balancing) | | `hostname` | Hostname for the API. The value cannot be empty.`"*"` matches any hostname. | | **Configure the client identifiers (for example, cookie, API key, OAuth2 token) used by the API** | | | `cookie` | Name of cookie used by the backend servers. | | `cookie_idle_timeout``logout_api_enabled``cookie_persistence_enabled` | N/A | | `oauth2_access_token` | When `true`, ASE captures OAuth2 Access Tokens.When `false`, ASE does not look for OAuth2 Tokens.Default value is `false`.For more information, see [Capture client identifiers - Sideband](pingintelligence_capture_client_identifiers.html). | | `is_token_mandatory` | When set to`true`, if the request has a missing token, ASE adds the IP address of the client to blacklist and blocks the request. When set to`false`, ASE does not block the client. For ASE to check and block the client the following values must be set to true: oauth2\_access\_token enable\_firewall and enable\_ase\_detected\_attack in Sideband ASE configuration using the ase.conf fileThe default value is `false`. | | `apikey_qs` | When API key is sent in the query string, ASE uses the specified parameter name to capture the API key value.For more information, see Configuring API keys. | | `apikey_header` | When API key is part of the header field, ASE uses the specified parameter name to capture the API key value.For more information, see [Capture client identifiers - Sideband](pingintelligence_capture_client_identifiers.html). | | `login_url` | Public URL used by a client to connect to the application. | | `enable_blocking` | When `true`, ASE blocks all types of attack on this API. When `false`, no attacks are blocked.Default value is `false`. | | `api_mapping` | N/A | | **API pattern enforcement**`protocol_allowed``http_redirect``methods_allowed``content_type_allowed``error_code``error_type``error_message_body` | N/A | | **Flow control**`client_spike_threshold``client_connection_queuing` | N/A | | `api_memory_size` | Maximum ASE memory allocation for an API.The default value is 128 MB. The data unit can be MB or GB. | | **Health\_check**`health_check_interval``health_retry_count``health_url` | N/A | | `server_ssl` | N/A | | **Servers:**`host``port` | The IP address or hostname and port number of each backend server running the API. | | `server_spike_threshold``server_connection_quota` | N/A | | **Decoy Config**`decoy_enabled``response_code``response_def response_message``decoy_subpaths` | When `decoy_enabled` is set to `true`, decoy sub-paths function as decoy APIs .`response_code` is the status code (for example `200`) that ASE returns when a decoy API path is accessed.`response_def` is the response definition (for example `OK`) that ASE returns when a decoy API path is accessed.`response_message`is the response message (for example `OK)` that ASE returns when a decoy API path is accessed.`decoy_subpaths`is the list of decoy API sub-paths (for example `shop/admin, shop/root)`See [Configuring API deception](pingintelligence_api_deception_environment_sideband.html) for details. | | `username_header` | The name of the custom header containing username. When the value of `username_header` is set, ASE extracts the username from the custom header. For more information, see [Extract username from custom header in sideband mode](pingintelligence_extract_username_custom_header_sideband.html). You can configure Username capture from either username\_header or JWT object, but not both. | | **JWT**`location``username``clientid` | When the parameter values of `JWT`object are set, ASE decodes the JWT to extract the user information from the JWT object.`location` is the place of occurrence of JWT in an API request. The supported values are:- `qs:` - `h:` - `h:authorization:bearer` - `h:authorization:mac` - `h:cookie:``username` is the JWT claim to extract the username.`clientid` is the JWT claim to extract the client-id.For more information, see [Extract user information from JWT in sideband mode](pingintelligence_exactract_user_informaton_jwt_sideband.html). You can configure Username capture from either JWT object or username\_header, but not both. | Here is a sample JSON file for a REST API: ```json { "api_metadata": { "protocol": "http", "url": "/rest", "hostname": "*", "cookie": "", "cookie_idle_timeout": "200m", "logout_api_enabled": false, "cookie_persistence_enabled": false, "oauth2_access_token": false, "is_token_mandatory": false, "apikey_qs": "", "apikey_header": "", "login_url": "", "enable_blocking": true, "api_mapping": { "internal_url": "" }, "api_pattern_enforcement": { "protocol_allowed": "", "http_redirect": { "response_code": "", "response_def": "", "https_url": "" }, "methods_allowed": [], "content_type_allowed": "", "error_code": "401", "error_def": "Unauthorized", "error_message_body": "401 Unauthorized" }, "flow_control": { "client_spike_threshold": "0/second", "server_connection_queueing": false }, "api_memory_size": "128mb", "health_check": false, "health_check_interval": 60, "health_retry_count": 4, "health_url": "/health", "health_check_headers": {}, "server_ssl": false, "servers": [ { "host": "127.0.0.1", "port": 8080, "server_spike_threshold": "0/second", "server_connection_quota": 0 }, { "host": "127.0.0.1", "port": 8081, "server_spike_threshold": "0/second", "server_connection_quota": 0 } ], "decoy_config": { "decoy_enabled": false, "response_code": 200, "response_def": "", "response_message": "", "decoy_subpaths": [] }, "username_header": "x-username-header", "jwt": { "location": "h:authorization:bearer", "username": "username", "clientid": "client_id" } } } ``` | | | | - | ----------------------------------------------------------------------------------------------------------------------------------- | | | The sample JSON file has an extension of `.example`. If you are customizing the example file, then save the file as a `.json` file. | ## Manually add API JSON to ASE After configuring an API JSON file, add it to ASE to activate ASE processing. To add an API, execute the following CLI command: ``` /opt/pingidentity/ase/bin/cli.sh –u admin -p admin add_api {file_path/api_name} ``` After configuring API JSON files for each API, ASE configuration is complete. ## Update a configured API JSON After activation, an API JSON definition can be updated in real time. Edit the API JSON file located in the `/config/api` directory and make the desired changes. Save the edited API JSON file and execute the following CLI command: ``` /opt/pingidentity/ase/bin/cli.sh –u admin -p admin update_api ``` For example: ``` /opt/pingidentity/ase/bin/cli.sh –u admin -p admin update_api shop api shop updated successfully ```