Skip to main content

​
API Reference

BotShield provides a REST API for integrating human presence verification into your platform. All SDK operations are server-to-server — there is no client-side library to install.
API access is provisioned through a developer application process. Request developer access to receive your API credentials.

​
Base URL

All SDK operations are served from: 
https://api.botshield.ai/operations
For local development with a test key: 
http://localhost:9991/operations

​
Authentication

All SDK operations require a Bearer token in the Authorization header. The token you use depends on the operation:
OperationToken TypePrefix
POST /sdk/create-sessionAPI Key (partner credential)bs_live_sk_ or bsk_test_
POST /sdk/create-verification-linkSession Token (from create-session)bss_
GET /verification/statusAPI Key (partner credential)bs_live_sk_ or bsk_test_
POST /sdk/logoutAPI Key (partner credential)bs_live_sk_ or bsk_test_

​
Example Header

Authorization: Bearer bs_live_sk_your_api_key_here

​
Environments

EnvironmentAPI Key PrefixPurpose
Productionbs_live_sk_Live verification with real users
Testbsk_test_Development and integration testing
Test keys allow you to complete the full integration flow without triggering real biometric verification.

​
SDK A Operations

BotShield SDK A (Signal-Only) exposes four operations:

Create Session

Initialize an anchor grant window. Returns a session token for subsequent operations.

Create Verification Link

Generate a verification request with deep link, web URL, and QR code for the user.

Verification Status

Poll for verification result. Returns the Human Presence Signal (HPS) when complete.

Logout Session

Revoke an active session token. Use for cleanup after verification completes.

​
Typical Integration Flow

1. POST /sdk/create-session
   → Returns session_token (bss_*)

2. POST /sdk/create-verification-link
   → Returns deep_link, web_url, qr_code_url, request_id

3. Present link to user (deep link / web URL / QR code)

4. User completes biometric verification in BotShield app

5. Receive result via:
   - Webhook POST → your server receives verification_token
   - OR poll GET /verification/status?request_id=...

6. Validate the verification_token (JWT) server-side

​
Error Handling

All endpoints return standard HTTP status codes:
CodeMeaning
200Success
400Bad Request — invalid or missing parameters
401Unauthorized — invalid or expired token
500Internal Server Error

​
Error Response Format

{
  "error": {
    "message": "Description of what went wrong",
    "statusCode": 400
  }
}

​
Validation Error Format

When input validation fails, the response includes details about each invalid field: 
{
  "message": "Invalid input provided",
  "input": { ... },
  "errors": [
    {
      "propertyPath": "email",
      "invalidValue": "not-an-email",
      "message": "must be a valid email address"
    }
  ]
}

​
Webhook Delivery

When you provide a webhook_url in the verification link request, BotShield will POST the result to your server when verification completes: 
{
  "event": "verification.completed",
  "request_id": "req_abc123",
  "status": "verified",
  "verification_token": "eyJhbGciOiJSUzI1NiIs...",
  "completed_at": "2025-01-15T10:30:00Z"
}
Your webhook endpoint should return a 200 status code to acknowledge receipt.

​
Rate Limits

Rate limits are applied per API key. If you exceed the limit, you will receive a 429 Too Many Requests response. Contact your account representative if you need higher limits.

​
Next Steps