Spring (Kotlin)
Install
Add the dependency to the project configuration:
Maven
1
2
3
4
5
<dependency>
<groupId>com.botbye</groupId>
<artifactId>kotlin-module</artifactId>
<version>3.0.1</version>
</dependency>
or
Gradle
1
implementation("com.botbye:kotlin-module:3.0.1")
Configuration
Create a configuration class using your server-key (available inside your Project). Build the client with Botbye.withExtractor(...) and bind a WebFlux extractor once: the SDK pulls ip/token/headers/method/uri out of each ServerHttpRequest, so your handlers pass only the raw request to the evaluate* methods and never assemble events by hand. The type parameter is your framework request type.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
@Configuration
class AppConfig {
@Bean
fun botbye(): Botbye<ServerHttpRequest> {
val config = BotbyeConfig(serverKey = "00000000-0000-0000-0000-000000000000") // Use your project server-key
return Botbye.withExtractor(config) { request ->
BotbyeRequestInfo(
ip = request.remoteAddress?.address?.hostAddress ?: "",
token = request.queryParams.getFirst("botbye_token") ?: "", // wherever you pass it: query param, header, body, etc.
headers = Headers(request.headers), // HttpHeaders is a multi-value Map<String, List<String>>; the SDK owns the flattening
requestMethod = request.method.name(),
requestUri = request.uri.path,
)
}
}
}
Usage
Per-Controller
Add evaluate in your controller for granular control over specific endpoints. Inject Botbye<ServerHttpRequest> and hand it the raw request — the bound extractor does the rest:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@RestController
@RequestMapping("/api/demo")
class DemoController(private val botbye: Botbye<ServerHttpRequest>) {
@PostMapping
suspend fun post(request: ServerHttpRequest): ResponseEntity<Any> {
val response = botbye.evaluateValidation(request)
if (response.isBlocked) {
return ResponseEntity.status(403).body("Access denied")
}
return ResponseEntity.ok().body("hello world!")
}
}
Global Filter (WebFlux CoWebFilter)
To protect all requests, create a Spring WebFlux filter with native coroutine support:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
@Component
class BotbyeFilter(private val botbye: Botbye<ServerHttpRequest>) : CoWebFilter() {
override suspend fun filter(exchange: ServerWebExchange, chain: CoWebFilterChain) {
val result = botbye.evaluateValidation(exchange.request)
if (result.isBlocked) {
exchange.response.statusCode = HttpStatus.FORBIDDEN
return
}
chain.filter(exchange)
}
}
There are three event types — validate, risk, and full — each suited for a different layer of your application.
validate — edge-level bot check
Use at the edge — API gateway, route handler, middleware — when you just want to know: was this request made by a bot? No user or domain context needed.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@RestController
@RequestMapping("/api/demo")
class DemoController(private val botbye: Botbye<ServerHttpRequest>) {
@PostMapping
suspend fun post(request: ServerHttpRequest): ResponseEntity<Any> {
val response = botbye.evaluateValidation(request)
if (response.isBlocked) {
return ResponseEntity.status(403).body("Access denied")
}
return ResponseEntity.ok().body("hello world!")
}
}
risk — domain-level risk scoring
Use inside services that already know the user: auth, payments, account management, etc. The purpose shifts from "is this a bot?" to "is something suspicious happening for this user?" — credential stuffing, account takeover, account sharing, logins from a new geo. Pass the same ServerHttpRequest down to the service so the extractor can attach request context to the risk event:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
@Service
class AuthService(private val botbye: Botbye<ServerHttpRequest>) {
suspend fun onLoginAttempt(request: ServerHttpRequest, userId: String, email: String, loginSucceeded: Boolean) {
val response = botbye.evaluateRiskScoring(
request,
user = BotbyeUserInfo(
accountId = userId,
email = email,
),
eventType = "login",
eventStatus = if (loginSucceeded) BotbyeEventStatus.SUCCESSFUL else BotbyeEventStatus.FAILED,
)
if (response.isBlocked) {
// Lock account, trigger MFA, send alert, etc.
}
}
}
Linking validate and risk events
When the same request is evaluated at two layers — for example, once at the edge (validate) and then again inside a domain service (risk) — BotBye can link both events and display them as a single event in the dashboard.
Step 1 — edge layer (filter, interceptor, or route handler): run validate and capture the result:
1
2
3
4
// e.g. in a CoWebFilter or route handler
val edgeResponse = botbye.evaluateValidation(request)
val edgeBotbyeResult = edgeResponse.botbyeResult
// Pass edgeBotbyeResult downstream — a request attribute, function argument, shared context, etc.
Step 2 — domain service (auth, payment, account management): pass it as botbyeResult in the risk call:
1
2
3
4
5
6
7
8
// e.g. in AuthService.onLoginAttempt()
val riskResponse = botbye.evaluateRiskScoring(
request,
user = BotbyeUserInfo(accountId = userId, email = email),
eventType = "login",
eventStatus = if (loginSucceeded) BotbyeEventStatus.SUCCESSFUL else BotbyeEventStatus.FAILED,
botbyeResult = edgeBotbyeResult,
)
botbyeResult is null when absent — in that case, omit it (or pass null) and the events will be recorded independently.
full — edge check and domain scoring in one call
Use when you have all context at once: raw request, token, user, and event. A login endpoint is a typical example — it receives the HTTP request and immediately knows the user and outcome.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
@RestController
@RequestMapping("/auth")
class LoginController(private val botbye: Botbye<ServerHttpRequest>) {
@PostMapping("/login")
suspend fun login(request: ServerHttpRequest, @RequestBody body: LoginRequest): ResponseEntity<Any> {
val user = findUser(body.email)
val loginSucceeded = user != null && checkPassword(user, body.password)
val response = botbye.evaluateFull(
request,
user = BotbyeUserInfo(
accountId = user?.id ?: "unknown",
email = body.email,
),
eventType = "login",
eventStatus = if (loginSucceeded) BotbyeEventStatus.SUCCESSFUL else BotbyeEventStatus.FAILED,
)
if (response.isBlocked) {
return ResponseEntity.status(403).body("Access denied")
}
return ResponseEntity.ok().body("Login successful")
}
}
Settings
BotbyeConfig contains next configurable parameters:
| Setting | Description | Required | Default Value |
|---|---|---|---|
| botbyeEndpoint | Host of the API Server | no | https://verify.botbye.com |
| serverKey | Your BotBye server-key | yes | - |
| contentType | Content type for API requests | no | application/json |
| readTimeout | Read timeout for HTTP client | no | Duration.ofSeconds(2) |
| writeTimeout | Write timeout for HTTP client | no | Duration.ofSeconds(2) |
| connectionTimeout | Connection timeout for HTTP client | no | Duration.ofSeconds(2) |
| callTimeout | Total call timeout | no | Duration.ofSeconds(5) |
| maxIdleConnections | Max idle connections in the pool | no | 250 |
| keepAliveDuration | Keep-alive duration | no | Duration.ofSeconds(300) |
| maxRequestsPerHost | Max requests per host | no | 1500 |
| maxRequests | Max requests total | no | 1500 |
Custom HTTP transport
The BotbyeConfig settings above tune the built-in OkHttp client. If you need a different HTTP stack entirely — your framework's own client, a shared pool, an outbound proxy — the SDK talks to BotBye only through the BotbyeHttpClient interface (OkHttp is just the default, OkHttpBotbyeClient). Implement the interface and pass it to the client; a transport you supply is caller-owned, so the SDK never closes it.
1
2
3
4
5
6
7
8
9
10
11
import com.botbye.common.http.BotbyeHttpClient
import com.botbye.common.http.BotbyeHttpRequest
import com.botbye.common.http.BotbyeHttpResponse
class MyHttpClient : BotbyeHttpClient {
override val type = "my-client"
override suspend fun call(request: BotbyeHttpRequest): BotbyeHttpResponse { /* ... */ }
}
// Pass it to either client (or the withExtractor factory):
val botbye = Botbye(config, client = MyHttpClient())
Examples of BotBye API responses
Blocked (bot detected):
1
2
3
4
5
6
7
{
"request_id": "f77b2abd-c5d7-44f0-be4f-174b04876583",
"decision": "BLOCK",
"risk_score": 0.95,
"scores": { "bot": 0.95 },
"signals": ["AutomationTool"]
}
Allowed:
1
2
3
4
5
6
7
{
"request_id": "f77b2abd-c5d7-44f0-be4f-174b04876583",
"decision": "ALLOW",
"risk_score": 0.05,
"scores": { "bot": 0.05, "ato": 0.02 },
"signals": []
}
Challenge:
1
2
3
4
5
6
7
8
{
"request_id": "f77b2abd-c5d7-44f0-be4f-174b04876583",
"decision": "CHALLENGE",
"risk_score": 0.65,
"scores": { "bot": 0.65 },
"signals": ["SuspiciousFingerprint"],
"challenge": { "type": "CAPTCHA" }
}
Invalid server-key — not a known project (fail-closed):
1
2
3
4
5
6
7
8
{
"request_id": "f77b2abd-c5d7-44f0-be4f-174b04876583",
"decision": "BLOCK",
"risk_score": 1.0,
"scores": {},
"signals": ["evaluation_error"],
"error": { "message": "Invalid server key" }
}
Evaluation error — request could not be processed (fail-closed):
1
2
3
4
5
6
7
8
{
"request_id": "f77b2abd-c5d7-44f0-be4f-174b04876583",
"decision": "BLOCK",
"risk_score": 1.0,
"scores": {},
"signals": ["evaluation_error"],
"error": { "message": "Invalid request body: missing or invalid field 'user.account_id'" }
}
SDK never received a decision (fail-open):
1
2
3
4
{
"decision": "ALLOW",
"error": { "message": "connection error" }
}