API Reference

Complete API documentation for server-side verification and site management.

Base URL

text

https://gkcaptcha.gatekeeper.sa/api/v1

Authentication

All API requests require authentication using your secret key:

http

Authorization: Bearer YOUR_SECRET_KEY

Never expose your secret key in client-side code.

Verify Token

Verify a CAPTCHA token received from the widget.

POST /api/v1/token/verify

Request Body

json

{
  "token": "captcha_token_from_widget",
  "ip": "optional_client_ip"
}

Response

json

{
  "success": true,
  "data": {
    "verified": true,
    "score": 0.15,
    "timestamp": "2024-01-15T10:30:00Z",
    "hostname": "example.com"
  }
}

Score (Invisible Mode)

Get a risk score without user interaction.

POST /api/v1/score

Response

json

{
  "success": true,
  "data": {
    "score": 0.25,
    "flags": ["suspicious_timing"],
    "action": "allow"
  }
}

Score Thresholds

Action	Score Range	Description
allow	0.0 - 0.3	Low risk, allow through
challenge	0.3 - 0.6	Medium risk, show CAPTCHA
block	0.6 - 1.0	High risk, block request

Error Codes

Code	Description
invalid_token	Token is invalid or expired
invalid_site_key	Site key not found
domain_mismatch	Request domain does not match site config
rate_limited	Too many requests
internal_error	Server error

Rate Limits

Endpoint	Limit
/api/v1/token/verify	1000/min per site
/api/v1/score	500/min per site
/api/v1/pow/challenge	100/min per account