--- title: The API JSON file description: The behavior and properties of your API are defined in an API JavaScript Object Notation (JSON) file in ASE. To enable username capture, set the values for the parameters defined in the JWT object of the API JSON file as per your API setup. For more information, see Defining an API using API JSON configuration file in sideband mode. component: pingintelligence version: 5.2 page_id: pingintelligence:pingintelligence_reference_guide:pingintelligence_api_json_file canonical_url: https://docs.pingidentity.com/pingintelligence/5.2/pingintelligence_reference_guide/pingintelligence_api_json_file.html revdate: April 3, 2024 --- # The API JSON file The behavior and properties of your API are defined in an API JavaScript Object Notation (JSON) *(tooltip: \
\

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

\
)* file in ASE. To enable username capture, set the values for the parameters defined in the JWT object of the API JSON file as per your API setup. For more information, see [Defining an API using API JSON configuration file in sideband mode](pingintelligence_define_api_json_file_sideband.html). The following is an example snippet of an API JSON file: ```json { "api_metadata": { "protocol": "http", "url": "/rest", "hostname": "*", "cookie": "", "cookie_idle_timeout": "200m", "logout_api_enabled": false, "cookie_persistence_enabled": false, "oauth2_access_token": true, "apikey_qs": "", "apikey_header": "", "login_url": "", "enable_blocking": true, "api_mapping": { "internal_url": "" }, "username_header": "", "jwt": { "location": "h:authorization:bearer", "username": "username", "clientid": "client_id" } } } ``` | | | | - | ---------------------------------------------------------------- | | | The values assigned to `username` and `clientid` cannot be same. | The following table explains the parameters in the JWT object of API JSON file. | Parameter | Description | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `location` | `location` is the place of occurrence of JWT in an API request. Configure the parameter with a value applicable to your API.The supported values for `location` parameter are:- `qs:` Set the location parameter with this value when JWT occurs as part of a query string and substitute the *\* with the query string parameter. For example,`"location": "qs: access_token"`.``` https://server.example.com/resource?access_token=mF_9.B5f-4.1JqM&p=q ```- `h:` Set the location parameter with this value when JWT is part of a custom header and substitute the *\* with custom header. For example,`"location": "h:X-jwt-header"`.``` X-jwt-header: eyJhbGcUzI1NiI.eyJzDkwIG4gRG9xpZWQiOjwMjJ9.DWw5PDZEl-g ```- `h:Authorization:bearer` Set the location parameter with this value when JWT is part of Authorization header, with bearer scheme. For example, `"location": "h:Authorization:bearer"`.``` Authorization: Bearer eyJhbGIUzIiI.eyJzdiIxG4gRG9lIiwiZiOjJ9.DWPwNDZEl-g ```- `h:cookie:` Set the location parameter with this value when JWT occurs as part of a cookie and substitute the *\* with the cookie name. For example, `"location": "h:cookie: access_token"`.``` Cookie: access_token=eyJhbGiIsI.eyJpc3MiOiJodHRwczotcGxlL.mFrs3ZodqKP4F1cB ``` | | `username` | The JWT claim to extract the username. | | `clientid` | The JWT claim to extract the client identifier. | When `enable_blocking` is set to `true`, ASE checks the username against the list of usernames in the allow list and deny list. If the username is in the deny list, the client using the username is blocked. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | ASE also supports extracting a username from a custom HTTP header. However, you can configure username capture from either custom header or JWT, but not both. For more information, see [Extract username from custom header in sideband mode](pingintelligence_extract_username_custom_header_sideband.html). |