> This page is for Applications Protection. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.humansecurity.com/llms.txt. # Configurations ## PerimeterX Configurations Required values: * [px\_app\_id](#px_app_id) * [px\_auth\_token](#px_auth_token) * [px\_cookie\_secret](#px_cookie_secret) ### px\_app\_id The application ID. Required to initialize the Enforcer. ```typescript const config: PerimeterXConfigurations = { // ... px_app_id: '', // ... } ``` ### px\_auth\_token The token used for authorization with the Human/PerimeterX backend. Required to initialize the Enforcer. ```typescript const config: PerimeterXConfigurations = { // ... px_auth_token: '', // ... } ``` ### px\_cookie\_secret The secret used to encrypt and decrypt the risk cookie. Required to initialize the Enforcer. ```typescript const config: PerimeterXConfigurations = { // ... px_cookie_secret: '', // ... } ``` ### onPass An optional handler that will be invoked for requests that pass HUMAN verification. The implementation can be the same handler used before installing the enforcer. * Parameters * request: [NextRequest](https://nextjs.org/docs/app/api-reference/functions/next-request) * Returns a [NextResponse](https://nextjs.org/docs/app/api-reference/functions/next-response) object (or a Promise resolving to a NextResponse) ```typescript const config: PerimeterXConfigurations = { // ... onPass: (request: NextRequest): NextResponse => { const response = NextResponse.next(); response.headers.set('test-header', 'test'); // Return the customized response return response; }, // ... } ``` ### onResponse An optional function that allows for modification of the response when the HUMAN middleware returns a custom response (for example, a block response). * Parameters * request: [NextRequest](https://nextjs.org/docs/app/api-reference/functions/next-request) * response: [NextResponse](https://nextjs.org/docs/app/api-reference/functions/next-response) * Returns a [NextResponse](https://nextjs.org/docs/app/api-reference/functions/next-response) object (or a Promise resolving to a NextResponse) ```typescript const config: PerimeterXConfigurations = { // ... onResponse: (request: NextRequest, response: NextResponse): NextResponse => { const nextResponse = NextResponse.next(); nextResponse.headers.set('X-PX-Status', response.headers.get('test')); // Return the customized response return nextResponse; }, // ... } ``` ### px\_module\_enabled This boolean serves as an on/off switch for the entire module, providing a way to enable and disable all Enforcer capabilities quickly and easily. **Default**: true ```typescript const config: PerimeterXConfigurations = { // ... px_module_enabled: false, // ... } ``` ### px\_module\_mode This feature controls the behavior of the enforcer by changing how it executes certain parts of the workflow. Most notably, different modes allow for analysis and fine-tuning of the enforcer behavior without serving block pages that affect end users. Possible values: * `monitor` - the enforcer will perform all functions without returning block responses * `active_blocking` - the enforcer will return block responses when needed **Default**: monitor ```typescript const config: PerimeterXConfigurations = { // ... px_module_mode: 'active_blocking', // ... } ``` ### px\_logger\_severity The verbosity of the logs generated by the enforcer. The enforcer will always use the `console.log()` function regardless of the configured logger severity. Possible values: * `none` - No logs will be generated * `error` - Sparse logs will be generated only when errors occur * `debug` - Detailed logs will always be generated (not advisable for production environments) **Default**: error ```typescript const config: PerimeterXConfigurations = { // ... px_logger_severity: 'debug', // ... } ``` ### px\_s2s\_timeout The maximum time in milliseconds to wait for the risk API request. If this timeout is reached, the original request will\ be allowed to pass (fail open). **Default**: 1000 ```typescript const config: PerimeterXConfigurations = { // ... px_s2s_timeout: 2000, // ... } ``` ### px\_ip\_headers By default, the IP is taken from `request.ip`. However, if this is inaccurate, the enforcer can extract the IP from the headers configured here. The headers are traversed in the order they are listed. The first header value that exists will be used as the client IP. **Default**: \[] ```typescript const config: PerimeterXConfigurations = { // ... px_ip_headers: ['true-ip', 'true-client-ip'], // ... } ``` ### px\_advanced\_blocking\_response\_enabled In specific cases (e.g., XHR post requests), a full captcha page render might not be an option. In such cases the advanced blocking response returns a JSON object containing all the information needed to render a customized captcha challenge implementation - be it a popup modal, a section on the page, etc. This allows for flexibility and customizability in terms of how the captcha pages are displayed. **Default**: true ```typescript const config: PerimeterXConfigurations = { // ... px_advanced_blocking_response_enabled: false, // ... } ``` ### px\_first\_party\_enabled To prevent suspicious or unwanted behavior on the client side, some browsers or extensions (e.g., adblockers) may deny the frontend JavaScript code from making requests to other domains. This prevents the PerimeterX sensor from making requests to the PerimeterX backends, which greatly limits PerimeterX's detection capabilities. To avoid this problem, first\_party enables the enforcer to be used as a proxy for PerimeterX servers, and to serve content to the browser from a first party endpoint (i.e., an endpoint on the customer’s domain). **Default**: true ```typescript const config: PerimeterXConfigurations = { // ... px_first_party_enabled: false, // ... } ``` ### px\_custom\_first\_party\_prefix By default, first party endpoints always begin with the application ID without the initial "PX". For example, if the application ID is `PX12345678`, then all first party routes will take the form `/12345678/*`. This configuration sets a custom prefix for first party routes to use in addition to the default prefix. When configured, the enforcer will respond to first party requests with endpoints matching the patterns `//init.js`, `//xhr/*`, and `//captcha/*`. **Default**: `""` (when empty, will use the default as described above) ```typescript const config: PerimeterXConfigurations = { // ... px_custom_first_party_prefix: "/custom-prefix", // ... } ``` ### px\_custom\_first\_party\_sensor\_endpoint For an application with ID `PX12345678`, the first party sensor endpoint is `/12345678/init.js` by default. This configuration customizes the entire first party sensor script endpoint. Note that in addition to responding to requests that match this configured route, the enforcer will also proxy first party requests that match the default pattern (`/12345678/init.js`) and patterns according to the custom prefix (`//init.js`) if one is configured. **Default**: `""` ```typescript const config: PerimeterXConfigurations = { // ... px_custom_first_party_sensor_endpoint: "/human_sensor", // ... } ``` ### px\_custom\_first\_party\_xhr\_endpoint For an application with ID `PX12345678`, the first party XHR endpoint is `/12345678/xhr` by default. This configuration customizes the first party XHR endpoint. Note that in addition to responding to requests that match this configured route, the enforcer will also proxy first party requests that match the default pattern (`/12345678/xhr/*`) and patterns according to the custom prefix (`//xhr/*`) if one is configured. **Default**: `""` ```typescript const config: PerimeterXConfigurations = { // ... px_custom_first_party_xhr_endpoint: "/human_xhr", // ... } ``` ### px\_custom\_first\_party\_captcha\_endpoint For an application with ID `PX12345678`, the first party captcha endpoint is `/12345678/captcha` by default. This configuration customizes the first party captcha endpoint. Note that in addition to responding to requests that match this configured route, the enforcer will also proxy first party requests that match the default pattern (`/12345678/captcha/*`) and patterns according to the custom prefix (`//captcha/*`) if one is configured. **Default**: `""` ```typescript const config: PerimeterXConfigurations = { // ... px_custom_first_party_captcha_endpoint: "/human_captcha", // ... } ``` ### px\_first\_party\_timeout\_ms The maximum time in milliseconds to wait for first party requests. **Default**: `4000` ```typescript const config: PerimeterXConfigurations = { // ... px_first_party_timeout_ms: 5000, // ... } ``` ### px\_bypass\_monitor\_header When enabling the enforcer for the first time, it is recommended to do so in monitor mode to collect data before actually starting to block user requests. Prior to switching the module mode to active\_blocking entirely, it's also crucial to verify that the full blocking flow works as expected. This feature activates the full blocking flow even while in monitor mode if a particular header is present on the request. **Default**: Empty ```typescript const config: PerimeterXConfigurations = { // ... px_bypass_monitor_header: 'x-px-block', // ... } ``` ### px\_enforced\_routes Customers may want certain, but not all, endpoints to be enforced by PerimeterX, even when the Enforcer is in Monitor Mode. These routes will go through the full enforcer workflow, including blocking requests when necessary. That is, even when the enforcer is in Monitor Mode, these defined routes will behave as if in Blocking Mode. **Default**: \[] ```typescript const config: PerimeterXConfigurations = { // ... px_enforced_routes: ['/enforced_route'], // ... } ``` ### px\_custom\_is\_enforced\_request > **Note** > > This configuration is meant for cases that require more complex custom logic. It is recommended to use the `px_enforced_routes` configuration for simpler cases. Customers may want certain, but not all, endpoints to be enforced by HUMAN, even when the Enforcer is in monitor mode. This configurable function provides a way to define which requests should be enforced based on custom logic. The function accepts the incoming request as an argument and returns a boolean indicating whether the request should be enforced (the request will behave as if in active blocking mode) or not. * Parameters * request: [NextRequest](https://nextjs.org/docs/app/api-reference/functions/next-request) * Returns a boolean (or a Promise resolving to a boolean) **Default**: `null` ```typescript const config: PerimeterXConfigurations = { // ... px_custom_is_enforced_request: (request: NextRequest): boolean | Promise => { return request.method === 'POST' && request.nextUrl.pathname.includes('/enforced_route'); }, // ... } ``` ### px\_monitored\_routes Enables certain endpoints to be monitored rather than enforced by PerimeterX, even when the enforcer is in active blocking mode. **Default**: \[] ```typescript const config: PerimeterXConfigurations = { // ... px_monitored_routes: ['/monitored_route'], // ... } ``` ### px\_custom\_is\_monitored\_request > **Note** > > This configuration is meant for cases that require more complex custom logic. It is recommended to use the `px_monitored_routes` configuration for simpler cases. Customers may want certain, but not all, endpoints to be monitored by HUMAN, even when the Enforcer is in active\_blocking mode. This configurable function provides a way to define which requests should be monitored based on custom logic. The function accepts the incoming request as an argument and returns a boolean indicating whether the request should be monitored (the request will behave as if in monitor mode) or not. * Parameters * request: [NextRequest](https://nextjs.org/docs/app/api-reference/functions/next-request) * Returns a boolean (or a Promise resolving to a boolean) **Default**: `null` ```typescript const config: PerimeterXConfigurations = { // ... px_custom_is_monitored_request: (request: NextRequest): boolean | Promise => { return request.method === 'GET' && request.nextUrl.pathname.includes('/monitored'); }, // ... } ``` #### `px_sensitive_headers` The PerimeterX detector requires information about the HTTP request as part of its bot detections. Certain headers may contain\ information that should not be forwarded to other servers, including the PerimeterX backend. Configuring these header names as\ sensitive headers will remove these headers from requests sent to other backends by PerimeterX. **Default**: \[`cookie`, `cookies`] ```typescript const config: PerimeterXConfigurations = { // ... px_sensitive_headers: ['x-sensitive-token'], // ... } ``` ### px\_sensitive\_routes Certain endpoints may require more stringent protection from bot attacks (e.g., endpoints that execute payments or handle personal information). In these cases, routes can be configured as sensitive routes, meaning risk API calls will be made even if the request contains a valid, unexpired cookie. **Default**: \[] ```typescript const config: PerimeterXConfigurations = { // ... px_sensitive_routes: ['/login', '/checkout'], // ... } ``` ### px\_custom\_is\_sensitive\_request > **Note** > > This configuration is meant for cases that require more complex custom logic. It is recommended to use the `px_sensitive_routes` configuration for simpler cases. Requests can be configured as sensitive, meaning risk API calls will be made even if the request contains a valid, unexpired cookie. This configurable function provides a way to define which requests should be considered sensitive based on custom logic. The function accepts the incoming request as an argument and returns a boolean indicating whether the request should be considered sensitive or not. * Parameters * request: [NextRequest](https://nextjs.org/docs/app/api-reference/functions/next-request) * Returns a boolean (or a Promise resolving to a boolean) **Default**: `null` ```typescript const config: PerimeterXConfigurations = { // ... px_custom_is_sensitive_request: (request: NextRequest): boolean | Promise => { return request.method === 'POST' || request.method === 'PUT'; }, // ... } ``` ### px\_filter\_by\_extension PerimeterX does not enforce static assets such as images and documents. To prevent unnecessary API calls to PerimeterX\ servers and needless computation, the enforcer filters all requests with a valid static file extension. Filtering by extension\ only applies to HTTP requests with methods GET and HEAD. **Default**: `['.css', '.bmp', '.tif', '.ttf', '.docx', '.woff2', '.js', '.pict', '.tiff', '.eot', '.xlsx', '.jpg', '.csv', '.eps', '.woff', '.xls', '.jpeg', '.doc', '.ejs', '.otf', '.pptx', '.gif', '.pdf', '.swf', '.svg', '.ps', '.ico', '.pls', '.midi', '.svgz', '.class', '.png', '.ppt', '.mid', '.webp', '.jar', '.json', '.xml']` ```typescript const config: PerimeterXConfigurations = { // ... px_filter_by_extension: ['.css', '.js', '.png'], // ... } ``` ### px\_filter\_by\_http\_method PerimeterX does not enforce static assets such as images and documents. To prevent unnecessary API calls to PerimeterX servers and needless computation, the enforcer filters all requests with a valid static file extension. **Default**: \[] ```typescript const config: PerimeterXConfigurations = { // ... px_filter_by_http_method: ['OPTIONS'], // ... } ``` ### px\_filter\_by\_ip Filters out requests according to their IP address, avoiding unnecessary traffic in the enforcer verification flow and reducing operation costs. **Default**: \[] ```typescript const config: PerimeterXConfigurations = { // ... px_filter_by_ip: ['1.1.1.1', '2.2.2.2/8'], // ... } ``` ### px\_filter\_by\_route Routes (endpoints) specified here will not be blocked, regardless of the score they receive. A client request to an allowed route will not generate any risk or async activities. **Default**: \[] ```typescript const config: PerimeterXConfigurations = { // ... px_filter_by_route: ['/filtered_route'], // ... } ``` ### px\_filter\_by\_user\_agent Filters out requests according to their user agent value, avoiding unnecessary traffic in the enforcer verification flow and reducing operation costs. **Default**: \[] ```typescript const config: PerimeterXConfigurations = { // ... px_filter_by_user_agent: ['filtered_UA'], // ... } ``` ### px\_custom\_is\_filtered\_request > **Note** > > This configuration is meant for cases that require more complex custom logic. It is recommended to use the `px_filter_by_route`, `px_filter_by_user_agent`, `px_filter_by_http_method`, `px_filter_by_ip`, and `px_filter_by_extension` configurations for simpler cases. Customers may prefer to filter certain requests (i.e., not apply HUMAN enforcement at all). These requests will not be blocked, and they will not generate any risk or async activities. This configurable function provides a way to define which requests should be filtered based on custom logic. The function accepts the incoming request as an argument and returns a boolean indicating whether the request should be filtered or not. * Parameters * request: [NextRequest](https://nextjs.org/docs/app/api-reference/functions/next-request) * Returns a boolean (or a Promise resolving to a boolean) **Default**: `null` ```typescript const config: PerimeterXConfigurations = { // ... px_custom_is_filtered_request: (request: NextRequest): boolean | Promise => { return request.method === 'GET' && request.nextUrl.pathname.includes('/static/'); }, // ... } ``` ### px\_css\_ref Provides a way to include an additional custom .css file to add to the block page. **Default**: Empty ```xml const config: PerimeterXConfigurations = { // ... px_css_ref: 'https://www.example.com/custom_style.css', // ... } ``` ### px\_js\_ref Provides a way to include a custom JS script to add to the block page. This script will run after the default JS scripts. **Default**: Empty ```typescript const config: PerimeterXConfigurations = { // ... px_js_ref: 'https://www.example.com/custom_script.js', // ... } ``` ### px\_custom\_logo Adds a custom logo to the block page that will be shown to users. This aligns the block page with the customer's brand. **Default**: Empty ```typescript const config: PerimeterXConfigurations = { // ... px_custom_logo: 'https://www.example.com/custom_logo.png', // ... } ``` ### px\_custom\_cookie\_header The Enforcer attempts to extract the PerimeterX cookies from the 'Cookie' header. If the PerimeterX cookies are transferred on a header other than 'Cookies', the header name should be configured here. **Default**: "x-px-cookies" ```typescript const config: PerimeterXConfigurations = { // ... px_custom_cookie_header: 'x-px-cookie', // ... } ``` ### px\_user\_agent\_max\_length The maximum length of the `User-Agent` header. If the user agent header value exceeds this length, it will be truncated to this length prior to processing. **Default**: 8528 ```typescript const config: PerimeterXConfigurations = { // ... px_user_agent_max_length: 2048, // ... } ``` ### px\_additional\_activity\_handler The additional activity handler is a custom function passed to the enforcer. The enforcer runs this callback after sending `page_requested` or `block` activity to the collector, and before forwarding the request to the next step in the pipeline. A common use case of the additional activity handler is to set the score as a variable or header. Then the application can read the score and do what is defined within the application's logic. * Parameters * config: PerimeterXConfigurations * context: IContext * * request: [NextRequest](https://nextjs.org/docs/app/api-reference/functions/next-request) * Returns void or a Promise resolving to void **Default**: null ```typescript const config: PerimeterXConfigurations = { // ... px_additional_activity_handler: ( config: PerimeterXConfigurations, context: IContext, request: NextRequest ): void => { ... }, // ... } ``` ### px\_enrich\_custom\_parameters This custom function enriches activities sent from the enforcer to PerimeterX with additional custom data. This data can include user information, session IDs, or other data that PerimeterX should have access to. These custom parameters are defined by a configurable function that must return an object that contains these custom parameters. There is a limit of 10 custom parameters. * Parameters * config: PerimeterXConfigurations * request: [NextRequest](https://nextjs.org/docs/app/api-reference/functions/next-request) * Returns CustomParameters | Promise\ **Default**: null ```typescript const config: PerimeterXConfigurations = { // ... px_enrich_custom_parameters: async ( config: PerimeterXConfigurations, request: NextRequest, ): `CustomParameters` | `Promise<`CustomParameters`>` => { const body = request.method === 'POST' && request.get('content-type')?.includes('application/json') ? request.body : null; return { custom_param1: 'hardcoded value', custom_param2: request.get('header-name'), custom_param3: body?.['body_property'] }; }, // ... } ``` ### px\_url\_decode\_reserved\_characters By design, the enforcer treats [reserved characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2) in URLs differently from their percent-encoded counterparts. For example, the URL `https://example.com/path-with-%3F-mark` will be parsed as having path `/path-with-%3F-mark`, while the URL `https://example.com/path-with-?-mark` would be parsed as having path `/path-with-` and query parameters `-mark`. However, some servers, frameworks, or business logic may apply percent decoding to reserved characters within the URL path. Setting this configuration to `true` will apply percent decoding to reserved characters in the URL path prior to parsing. **Default**: `false` ```typescript const config: PerimeterXConfigurations = { // ... px_url_decode_reserved_characters: true, // ... } ``` ## Account Defender Configurations ### px\_jwt\_cookie\_name The name of the cookie that contains the JWT token from which user identifiers should be extracted. **Default**: `""` ```typescript const config: PerimeterXConfigurations = { // ... px_jwt_cookie_name: 'auth', // ... } ``` ### px\_jwt\_cookie\_user\_id\_field\_name The field name in the JWT object, extracted from the JWT cookie, that contains the user ID to be extracted and reported. **Default**: `""` ```typescript const config: PerimeterXConfigurations = { // ... px_jwt_cookie_user_id_field_name: 'nameID', // ... } ``` ### px\_jwt\_cookie\_additional\_field\_names The field names in the JWT object, extracted from the JWT cookie, that should be extracted and reported in addition to the user ID. **Default**: `[]` ```typescript const config: PerimeterXConfigurations = { // ... px_jwt_cookie_additional_field_names: ['exp', 'iss'], // ... } ``` ### px\_jwt\_header\_name The name of the header that contains the JWT token from which user identifiers should be extracted. **Default**: `""` ```typescript const config: PerimeterXConfigurations = { // ... px_jwt_header_name: 'x-jwt-authorization', // ... } ``` ### px\_jwt\_header\_user\_id\_field\_name The field name in the JWT object, extracted from the JWT header, that contains the user ID to be extracted and reported. **Default**: `""` ```typescript const config: PerimeterXConfigurations = { // ... px_jwt_header_user_id_field_name: 'sub', // ... } ``` ### px\_jwt\_header\_additional\_field\_names The field names in the JWT object, extracted from the JWT header, that should be extracted and reported in addition to the user ID. **Default**: `[]` ```typescript const config: PerimeterXConfigurations = { // ... px_jwt_header_additional_field_names: ['exp', 'iss'], // ... } ``` ### px\_secured\_pxhd\_enabled > **This configuration was added in version 0.2.0.** Whether the PXHD cookie `_pxhd` set on the HTTP response should include the [Secure attribute](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies). Possible values: * `true` - PXHD cookie will be set with the `Secure` attribute * `false` - PXHD cookie will not be set with the `Secure` attribute **Default**: `false` ```typescript const config: PerimeterXConfigurations = { // ... px_secured_pxhd_enabled: true, // ... } ```