Kotlin SDK for Server-Side Bot Validation

Ktor

Install

Add the dependency to the project configuration:

Maven

<dependency>
    <groupId>com.botbye</groupId>
    <artifactId>kotlin-module</artifactId>
    <version>2.1.0</version>
</dependency>

Gradle

implementation("com.botbye:kotlin-module:2.1.0")

Configuration

Create BotbyeConfig with your server-key (available inside your Project):

1
2
3

val config = BotbyeConfig(serverKey = "00000000-0000-0000-0000-000000000000") // Use your project server-key

val botbye = Botbye(config)

Usage

Add a Ktor plugin to evaluate all incoming requests:

import com.botbye.Botbye
import com.botbye.model.evaluate.BotbyeValidationEvent
import io.ktor.http.*
import io.ktor.server.application.*
import io.ktor.server.response.*

fun Application.configureBotbye(botbye: Botbye) {
    intercept(ApplicationCallPipeline.Plugins) {
        val headers = call.request.headers.entries()
            .associate { (k, v) -> k to v.joinToString(", ") }

        // Extract the token from wherever you pass it: query param, header, body, etc.
        val token = call.request.queryParameters["botbye_token"] ?: ""

        val response = botbye.evaluate(BotbyeValidationEvent(
            ip = call.request.local.remoteAddress,
            token = token,
            headers = headers,
            requestMethod = call.request.local.method.value,
            requestUri = call.request.local.uri,
        ))

        if (response.isBlocked) {
            call.respond(HttpStatusCode.Forbidden, "Access denied")
            finish()
            return@intercept
        }
    }
}

Install the plugin in your application module:

fun main() {
    embeddedServer(Netty, port = 8080) {
        val config = BotbyeConfig(
            serverKey = "00000000-0000-0000-0000-000000000000" // Use your project server-key
        )
        val botbye = Botbye(config)

        configureBotbye(botbye)

        routing {
            post("/api/demo") {
                call.respondText("hello world!")
            }
        }
    }.start(wait = true)
}

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.

import com.botbye.Botbye
import com.botbye.model.evaluate.BotbyeValidationEvent
import io.ktor.http.*
import io.ktor.server.application.*
import io.ktor.server.response.*

fun Application.configureBotbye(botbye: Botbye) {
    intercept(ApplicationCallPipeline.Plugins) {
        val headers = call.request.headers.entries()
            .associate { (k, v) -> k to v.joinToString(", ") }

        // Extract the token from wherever you pass it: query param, header, body, etc.
        val token = call.request.queryParameters["botbye_token"] ?: ""

        val response = botbye.evaluate(BotbyeValidationEvent(
            ip = call.request.local.remoteAddress,
            token = token,
            headers = headers,
            requestMethod = call.request.local.method.value,
            requestUri = call.request.local.uri,
        ))

        if (response.isBlocked) {
            call.respond(HttpStatusCode.Forbidden, "Access denied")
            finish()
            return@intercept
        }
    }
}

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.

import com.botbye.Botbye
import com.botbye.model.evaluate.BotbyeRiskScoringEvent
import com.botbye.model.evaluate.BotbyeUserInfo
import com.botbye.model.evaluate.BotbyeEventStatus
import io.ktor.http.*
import io.ktor.server.application.*
import io.ktor.server.response.*

fun Route.loginRoute(botbye: Botbye) {
    post("/auth/login") {
        val ip = call.request.local.remoteAddress
        val body = call.receive<LoginRequest>()

        val user = findUser(body.email)
        val loginSucceeded = user != null && checkPassword(user, body.password)

        val response = botbye.evaluate(BotbyeRiskScoringEvent(
            ip = ip,
            headers = emptyMap(),
            user = BotbyeUserInfo(
                accountId = user?.id ?: "unknown",
                email = body.email,
            ),
            eventType = "login",
            eventStatus = if (loginSucceeded) BotbyeEventStatus.SUCCESSFUL else BotbyeEventStatus.FAILED,
            botbyeResult = null, // if a validate call was made earlier, pass response.botbyeResult here to link the requests; omit if there was no prior validate
        ))

        if (response.isBlocked) {
            call.respond(HttpStatusCode.Forbidden, "Access denied")
            return@post
        }

        call.respondText("Login successful")
    }
}

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 (plugin interceptor or route handler): run validate and capture the result:

// e.g. in configureBotbye() interceptor
val edgeResponse = botbye.evaluate(BotbyeValidationEvent(
    ip = call.request.local.remoteAddress,
    token = token,
    headers = headers,
    requestMethod = call.request.local.method.value,
    requestUri = call.request.local.uri,
))
val edgeBotbyeResult = edgeResponse.botbyeResult
// Pass edgeBotbyeResult downstream — a call attribute, function argument, shared context, etc.

Step 2 — domain service (auth, payment, account management): pass it as botbyeResult in the risk call:

// e.g. in AuthService.onLoginAttempt()
val riskResponse = botbye.evaluate(BotbyeRiskScoringEvent(
    ip = ip,
    headers = emptyMap(),
    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 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.

import com.botbye.Botbye
import com.botbye.model.evaluate.BotbyeFullEvent
import com.botbye.model.evaluate.BotbyeUserInfo
import com.botbye.model.evaluate.BotbyeEventStatus
import io.ktor.http.*
import io.ktor.server.application.*
import io.ktor.server.response.*

fun Route.loginRoute(botbye: Botbye) {
    post("/auth/login") {
        val headers = call.request.headers.entries()
            .associate { (k, v) -> k to v.joinToString(", ") }
        val token = call.request.queryParameters["botbye_token"] ?: ""

        val body = call.receive<LoginRequest>()
        val user = findUser(body.email)
        val loginSucceeded = user != null && checkPassword(user, body.password)

        val response = botbye.evaluate(BotbyeFullEvent(
            ip = call.request.local.remoteAddress,
            token = token,
            headers = headers,
            requestMethod = call.request.local.method.value,
            requestUri = call.request.local.uri,
            user = BotbyeUserInfo(
                accountId = user?.id ?: "unknown",
                email = body.email,
            ),
            eventType = "login",
            eventStatus = if (loginSucceeded) BotbyeEventStatus.SUCCESSFUL else BotbyeEventStatus.FAILED,
        ))

        if (response.isBlocked) {
            call.respond(HttpStatusCode.Forbidden, "Access denied")
            return@post
        }

        call.respondText("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

Examples of BotBye API responses

Blocked (bot detected):

{
  "request_id": "f77b2abd-c5d7-44f0-be4f-174b04876583",
  "decision": "BLOCK",
  "risk_score": 0.95,
  "scores": { "bot": 0.95 },
  "signals": ["AutomationTool"]
}

Allowed:

{
  "request_id": "f77b2abd-c5d7-44f0-be4f-174b04876583",
  "decision": "ALLOW",
  "risk_score": 0.05,
  "scores": { "bot": 0.05, "ato": 0.02 },
  "signals": []
}

Challenge:

{
  "request_id": "f77b2abd-c5d7-44f0-be4f-174b04876583",
  "decision": "CHALLENGE",
  "risk_score": 0.65,
  "scores": { "bot": 0.65 },
  "signals": ["SuspiciousFingerprint"],
  "challenge": { "type": "captcha", "token": "..." }
}

Invalid server-key:

{
  "decision": "ALLOW",
  "error": { "message": "[BotBye] Bad Request: Invalid Server Key" }
}