The BotBye API offers the capability to approve or deny any HTTP request depending on its characteristics.
Modules integrated into a component of your backend infrastructure (CDN, load balancer, application server, etc.) should submit validation requests to the BotBye API.
The POST request should be sent to the url https://api.botbye.com/validate-request/v2?botbye_token. Where the botbye_token obtained from the client integration must be attached as a request parameter by first encodeURI(*different in different environments).
Required parameters of the request body:
- server_key
- request_info
- remote_addr: String
- request_method: String
- request_uri: String
- created_at: Unix Timestamp(s)
- server_port: String
- server_name: String
- headers
Optional:
- custom_fields
Example
A request was received on the backend where the client integration added the following value to the x-botbye-token header:
1
2
3
{
x-botbye-token: visitorId=7fTFZxJOUx&sessionId=AahmrIMA&token=1%7C72a15f6a2e8f02e9%7C%2FX9fZJc7PdANZzahFWjNlUzNmaj%2FZUQmJTR2vkR7%2BZhzj7cZKGAsGdpsCOassA1btL2hsgYWdcsky9I0Rtic5UgJbL36F1klW9LPwKY3kms%3D%7C
}
Extract the token from the header and apply encodeURI() to it (*this might vary depending on the platform).
Example of the resulting curl request:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
curl --location 'https://verify.botbye.com/validate-request/v2?visitorId=7fTFZxJOUx&sessionId=AahmrIMA&token=1%257C72a15f6a2e8f02e9%257C%252FX9fZJc7PdANZzahFWjNlUzNmaj%252FZUQmJTR2vkR7%252BZhzj7cZKGAsGdpsCOassA1btL2hsgYWdcsky9I0Rtic5UgJbL36F1klW9LPwKY3kms%253D%257C' \
--header 'Content-Type: application/json' \--data '{
"request_info": {
"created_at": 1700142981.95,
"server_port": "80",
"remote_addr": "172.18.0.1",
"server_name": "localhost",
"request_method": "GET",
"request_uri": "\/login"
},
"server_key": "00000000-0000-0000-0000-000000000000", # Use your project server-key
"headers": {
"host": "localhost:8080",
"content-type": "application\/json",
"connection": "keep-alive",
"accept": "*\/*",
"accept-encoding": "gzip, deflate, br"
},
"custom_fields": {
"someKey": "some-value"
}
}''
Examples of BotBye API responses
Bot detected:
1
2
3
4
5
6
7
{
"reqId": "f77b2abd-c5d7-44f0-be4f-174b04876583",
"result": {
"isAllowed": false
},
"error": "Automation tool used"
}
Bot not detected:
1
2
3
4
5
6
7
{
"reqId": "f77b2abd-c5d7-44f0-be4f-174b04876583",
"result": {
"isAllowed": true
},
"error": null
}
Request banned by custom rule:
1
2
3
4
5
6
7
8
9
{
"reqId": "f77b2abd-c5d7-44f0-be4f-174b04876583",
"result": {
"isAllowed": false
},
"error": {
"message": "Banned by rule: MY_CUSTOM_RULE"
}
}
Invalid server-key:
1
2
3
4
5
6
7
{
"reqId": "f77b2abd-c5d7-44f0-be4f-174b04876583",
"result": null,
"error": {
"message": "[BotBye] Bad Request: Invalid Server Key"
}
}