> 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. # Enforce an HTTP request POST sapi-123456789.perimeterx.net/api/v1/enforce/risk Content-Type: application/json Processes an HTTP request and returns an enforcement response. Reference: https://docs.humansecurity.com/applications/reference/request ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Body (application/json) This endpoint expects an object. - `request` (EnforceRiskPostRequestBodyContentApplicationJsonSchemaRequest, required) — The HTTP request that should be enforced. - `additional` (EnforceRiskPostRequestBodyContentApplicationJsonSchemaAdditional, optional) — Any additional data to consider while processing the HTTP request. ## Response ### 200 success - `status` (enum, optional) — Whether the Enforce API call was successful. `0` for success, `-1` for failure. - Allowed values: `0`, `-1` - `score` (double, optional) — The risk score associated with the request on a scale of 0-100, where 0 is not a bot and 100 is a bot. - `action` (enum, optional) — The type of block response that should be returned to the end user. See Possible values: - `c`: Captcha. See [HUMAN Challenge](/applications/create-a-human-challenge) for details. - `b`: Hard block. See [Create custom Traffic policy rules](/applications/create-custom-traffic-policy-rules) for details. - `r`: Rate limit. See [Traffic policy settings](/applications/traffic-policy-settings#rate-limiting-rules) for details. - `a`: Allow. - Allowed values: `c`, `b`, `r`, `a` - `pxhd` (string, optional) — A hashed data value that should be set on the returned response as the `_pxhd` cookie - `uuid` (string, optional) — The unique ID associated with the web interaction this request was a part of. - `vid` (string, optional) — The unique ID associated with the user who sent the request if known. - `data_enrichment` (EnforceSuccessDataEnrichment, optional) — A data enrichment object with additioanl information about the detection that was performed on the request. See [Data classification enrichment](/applications/data-classification-enrichment#available-enrichment-data-by-type) for details. In the scope of the integration, the most relevant fields are: - `cgp`: Holds a value of 1 once a Challenge is successfully solved for the configured grace period. This defaults to 15 minutes and can be changed upon request. If a challenge is not solved, if the grace period passes, or if the request was reidentified as a bot (such as going above the request volume threshold), the `cgp` flag will be empty or have a value of 0. If the request was reidentified as a bot, the score and action will also be updated accordingly. - `bm`: Holds a value of 1 if the request is in bypass mode. If the traffic is not in bypass mode, the field won't be a part of the data enrichment. Therefore, either `bm: 1` appears if bypass mode is enabled, or it will not appear at all. ## Errors ### 400 Bad Request Error The request body is not in the correct format. - `any` ### 401 Unauthorized Error The `Authorization` header is missing or incorrect. - `any` ### 415 Unsupported Media Type Error The `Content-Type` header is not `application/json`. - `any` ## Types ### EnforceRiskPostRequestBodyContentApplicationJsonSchemaRequest The HTTP request that should be enforced. - `url` (string, required) — The full URL of the HTTP request including protocol, domain, and path. - `client_ip` (string, required) — The client IP of the request. - `method` (string, required) — The HTTP method of the request. - `headers` (list of EnforceRiskPostRequestBodyContentApplicationJsonSchemaRequestHeadersItems, required) — An array of objects where each object represents a header name and value pair. Whenever possible, the order of the headers in the original request should be preserved. Headers with sensitive data or PII should **not** be included. Note that the `User-Agent` header is crucial, and the following headers should be sent whenever possible: - `referer` - `user-agent` - `x-px-access-token` - `x-forwarded-for` - `x-real-ip` - `x-cluster-client-ip` - `x-forwarded` - `forwarded-for` - `forwarded` - `host` - `origin` - `accept` - `x-requested-with` - `x-px-authorization` - `x-px-bypass-reason` - `content-length` ### EnforceRiskPostRequestBodyContentApplicationJsonSchemaAdditional Any additional data to consider while processing the HTTP request. - `px3` (string, optional) — The value of the `_px3` cookie. - `pxcts` (string, optional) — The value of the `_pxcts` cookie. - `pxvid` (string, optional) — The value of the `_pxvid` cookie. - `x_px_authorization` (string, optional) — The value of the `x-px-authorization` header if it exists. This header is used for requests from the hUMAN mobile SDK. - `http_version` (string, optional) — The HTTP version of the request. - `request_cookie_names` (list of string, optional) — An array of strings representing the cookie names present on the request. The array should contain the cookie names only. Cookie values should **not** be included. - `tls_protocol` (string, optional) — The TLS version used for the HTTPS request. - `tls_ja3_fingerprint` (string, optional) — The JA3 fingerprint used for the HTTPS request. - `tls_ja4_fingerprint` (string, optional) — The JA4 fingerprint used for the HTTPS request. - `tls_cipher` (string, optional) — The TLS cipher used for the HTTPS request. - `tls_cipher_sha` (string, optional) — The TLS cipher hash used for the HTTPS request. - `tls_extension_sha` (string, optional) — The hash for the TLS extension identifiers sent from the client as part of the TLS handshake. - `tls_preferred_ciphers` (string, optional) — The client's preferred TLS ciphers for the HTTPS request. - `custom_parameters` (map from string to string, optional) — Custom data that will be sent to HUMAN on this request. This can include user information, session IDs, or other data that HUMAN should have access to and utilize in the detection engine and when visualizing traffic and decisions. All keys must take the form `custom_param1` through `custom_param10`. ### EnforceSuccessDataEnrichment A data enrichment object with additioanl information about the detection that was performed on the request. See [Data classification enrichment](/applications/data-classification-enrichment#available-enrichment-data-by-type) for details. In the scope of the integration, the most relevant fields are: - `cgp`: Holds a value of 1 once a Challenge is successfully solved for the configured grace period. This defaults to 15 minutes and can be changed upon request. If a challenge is not solved, if the grace period passes, or if the request was reidentified as a bot (such as going above the request volume threshold), the `cgp` flag will be empty or have a value of 0. If the request was reidentified as a bot, the score and action will also be updated accordingly. - `bm`: Holds a value of 1 if the request is in bypass mode. If the traffic is not in bypass mode, the field won't be a part of the data enrichment. Therefore, either `bm: 1` appears if bypass mode is enabled, or it will not appear at all. - `timestamp` (string, optional) — The time the cookie was created. - `f_type` (enum, optional) — The access control rule type. `w` for whitelist, `b` for blacklist. - Allowed values: `w`, `b` - `f_id` (string, optional) — The access control rule ID. These are available in its JSON directory. - `f_origin` (string, optional) — Whether the data is defined as a custom rule or as a default HUMAN rule. Rules from **Known bots & crawlers** and **IP Classification** will always be `px`. - `f_kb` (enum, optional) — Whether the request was made by a known bot or not. `1` for known bot, `0` for other. - Allowed values: `0`, `1` - `ipc_id` (list of string, optional) — An array of IP categorication IDs. These are available in its JSON directory. - `inc_id` (list of string, optional) — An array of hashed incident types. - `cgp` (enum, optional) — "CAPTCHA grace period". Whether the CAPTCHA was solved within the CAPTCHA grace period. `1` for in bypass, which means the user solved the CAPTCHA within the grace period. If not in bypass, this field does not appear. - Allowed values: `1` - `bm` (enum, optional) — "Bypass mode". When a request is in bypass mode, certain security checks or mitigations are skipped and the request is allowed to proceed. `1` for when bypass is enabled. If not enabled, this field does not appear. - Allowed values: `1` - `f_access_token` (string, optional) — The access token name. Only appears if `f_type` is `whitelist` and filter reason is `access_token`. - `breached_account` (enum, optional) — Whether the credentials on the activity were identified as compromised. `1` if true, otherwise the field will not appear. - Allowed values: `1` ### EnforceRiskPostRequestBodyContentApplicationJsonSchemaRequestHeadersItems - `name` (string, optional) - `value` (string, optional) ## Examples **Request** ```json { "request": { "url": "https://www.example.com/path?query=string", "client_ip": "1.2.3.4", "method": "POST", "headers": [ { "name": "User-Agent", "value": "TestUserAgent" }, { "name": "Content-Type", "value": "application/json" }, { "name": "Content-Length", "value": "129" } ] } } ``` **Response** ```json { "status": 0, "score": 100, "action": "c", "pxhd": "0000000000000000000000000000000000000000000000000000000000000000:00000000-0000-0000-0000-000000000000", "uuid": "00000000-0000-0000-0000-000000000000", "vid": "00000000-0000-0000-0000-000000000000", "data_enrichment": { "timestamp": "1729724240012", "f_type": "b", "f_id": "00000000-0000-0000-0000-000000000000", "f_origin": "custom", "f_kb": 0, "ipc_id": [], "inc_id": [ "00000000000000000000000000000000" ] } } ``` **SDK Code** ```python import requests url = "https://sapi-123456789.perimeterx.net/api/v1/enforce/risk" payload = { "request": { "url": "https://www.example.com/path?query=string", "client_ip": "1.2.3.4", "method": "POST", "headers": [ { "name": "User-Agent", "value": "TestUserAgent" }, { "name": "Content-Type", "value": "application/json" }, { "name": "Content-Length", "value": "129" } ] } } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://sapi-123456789.perimeterx.net/api/v1/enforce/risk'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"request":{"url":"https://www.example.com/path?query=string","client_ip":"1.2.3.4","method":"POST","headers":[{"name":"User-Agent","value":"TestUserAgent"},{"name":"Content-Type","value":"application/json"},{"name":"Content-Length","value":"129"}]}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://sapi-123456789.perimeterx.net/api/v1/enforce/risk" payload := strings.NewReader("{\n \"request\": {\n \"url\": \"https://www.example.com/path?query=string\",\n \"client_ip\": \"1.2.3.4\",\n \"method\": \"POST\",\n \"headers\": [\n {\n \"name\": \"User-Agent\",\n \"value\": \"TestUserAgent\"\n },\n {\n \"name\": \"Content-Type\",\n \"value\": \"application/json\"\n },\n {\n \"name\": \"Content-Length\",\n \"value\": \"129\"\n }\n ]\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://sapi-123456789.perimeterx.net/api/v1/enforce/risk") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"request\": {\n \"url\": \"https://www.example.com/path?query=string\",\n \"client_ip\": \"1.2.3.4\",\n \"method\": \"POST\",\n \"headers\": [\n {\n \"name\": \"User-Agent\",\n \"value\": \"TestUserAgent\"\n },\n {\n \"name\": \"Content-Type\",\n \"value\": \"application/json\"\n },\n {\n \"name\": \"Content-Length\",\n \"value\": \"129\"\n }\n ]\n }\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://sapi-123456789.perimeterx.net/api/v1/enforce/risk") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"request\": {\n \"url\": \"https://www.example.com/path?query=string\",\n \"client_ip\": \"1.2.3.4\",\n \"method\": \"POST\",\n \"headers\": [\n {\n \"name\": \"User-Agent\",\n \"value\": \"TestUserAgent\"\n },\n {\n \"name\": \"Content-Type\",\n \"value\": \"application/json\"\n },\n {\n \"name\": \"Content-Length\",\n \"value\": \"129\"\n }\n ]\n }\n}") .asString(); ``` ```php request('POST', 'https://sapi-123456789.perimeterx.net/api/v1/enforce/risk', [ 'body' => '{ "request": { "url": "https://www.example.com/path?query=string", "client_ip": "1.2.3.4", "method": "POST", "headers": [ { "name": "User-Agent", "value": "TestUserAgent" }, { "name": "Content-Type", "value": "application/json" }, { "name": "Content-Length", "value": "129" } ] } }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://sapi-123456789.perimeterx.net/api/v1/enforce/risk"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"request\": {\n \"url\": \"https://www.example.com/path?query=string\",\n \"client_ip\": \"1.2.3.4\",\n \"method\": \"POST\",\n \"headers\": [\n {\n \"name\": \"User-Agent\",\n \"value\": \"TestUserAgent\"\n },\n {\n \"name\": \"Content-Type\",\n \"value\": \"application/json\"\n },\n {\n \"name\": \"Content-Length\",\n \"value\": \"129\"\n }\n ]\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["request": [ "url": "https://www.example.com/path?query=string", "client_ip": "1.2.3.4", "method": "POST", "headers": [ [ "name": "User-Agent", "value": "TestUserAgent" ], [ "name": "Content-Type", "value": "application/json" ], [ "name": "Content-Length", "value": "129" ] ] ]] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://sapi-123456789.perimeterx.net/api/v1/enforce/risk")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```