@bespot/gatekeeper-web-sdk

Bespot Gatekeeper Web SDK

Web SDK for Bespot Gatekeeper, a fraud prevention and location integrity platform for web applications.

Use this SDK to run real-time fraud checks in browser sessions and receive policy results for high-risk actions such as signup, login, checkout, reward redemption, wallet actions, account changes, or location-restricted access.

Gatekeeper helps detect and evaluate bot traffic, AI agents, location spoofing, VPN/proxy use, suspicious browser or device signals, multi-accounting, and abuse patterns such as bonus, promo, or reward fraud.

Prerequisites

Before integrating, sign up at gatekeeper.bespot.com to create your account and obtain your API key and other credentials for SDK runtime configuration.

Documentation

SDK integration guides live in this repository. Official Bespot product documentation is at docs.bespot.com.

Document	Description
Integration guide	Full end-to-end integration reference
Authentication	JWT access tokens and OAuth (server-side)
Error reference	Error handling rules and error.name catalog
SDK versioning	SDK package version vs application version
Templates	Copy-paste HTML and config starters
Sandbox	Manual UMD/ESM credential check against dist/

Official authentication API reference: Bespot Authentication Guide.

Installation

SDK bundles are distributed via npm and GitHub Releases (safe-sdk.esm.min.js, safe-sdk.umd.min.js). Each release includes both ESM and UMD builds — download and host directly; no extraction step required.

npm (recommended)

Requires Node.js on your development machine to run npm install. The SDK itself runs in the browser — Node is not needed at runtime.

npm install @bespot/gatekeeper-web-sdk

import SafeSDK from '@bespot/gatekeeper-web-sdk'

CDN / script tag (no build step)

No Node.js required. Download safe-sdk.esm.min.js or safe-sdk.umd.min.js from the Releases page and host the files on your CDN or static origin.

Quick start

• Account — sign in at gatekeeper.bespot.com and collect your credentials
• Install — npm install @bespot/gatekeeper-web-sdk or download from Releases
• Configure — four runtime fields: baseUrl, apiKey, applicationId, applicationVersion (runtime configuration)
• Authenticate — obtain a JWT from your backend (authentication)
• Integrate — await sdk.initialize(jwt) then await sdk.check() (integration sequence)
• Optional — verify credentials — from this repo run npm run sandbox (sandbox README)

const sdk = new SafeSDK({
  baseUrl: 'bespot-gatekeeper-base-url', // e.g. 'https://gatekeeper.bespotcompany.com'
  apiKey: 'your-api-key', // e.g. '13CTrcYiya9NNnRyd3jXA21CULPPDSqM90sdFnGs'
  applicationId: 'your-app-id', // e.g. 'mywebapp.mycompany.com'
  applicationVersion: 'your-app-version', // e.g. '2.4.1'
})

await sdk.initialize(jwt)

const result = await sdk.check()
if (result instanceof Error) {
  console.error('Check failed:', result.name)
} else {
  console.log('Check passed:', result)
}

Starter pages: templates/integration-esm.html, templates/integration-umd.html. Credentials sandbox: examples/sandbox/.

Network behavior

This SDK makes runtime-only HTTPS requests to the Gatekeeper API URL you configure in baseUrl:

• POST /device/{applicationId}/{applicationVersion}/register — on initialize()

• POST /device/{applicationId}/{applicationVersion}/check — on check() and periodic checks

• No install scripts (preinstall, postinstall, etc.)

• No network activity during npm install

• Network requests occur during initialize(), check(), and optionally during periodic checks if you call subscribe() (see periodic checks)

• Requests use the browser fetch API with a 30-second timeout, your API key, and JWT

This behavior is required for Gatekeeper fraud and location checks.

Data collection

During initialize() and check() (and periodic checks when subscribe() is active), the SDK collects browser and device signals needed for fraud prevention and location integrity:

• Device fingerprint — canvas, WebGL, and audio signals are hashed into a deterministic device_seed (raw fingerprint values are not transmitted)
• Geolocation — browser Geolocation API when the user grants permission (see geolocation)
• Browser and device metadata — user agent, screen, locale, connection type, and related fields included in check payloads
• Persistent identifiers — session data stored across localStorage, sessionStorage, cookies, and IndexedDB for device continuity across visits

Collection happens only at runtime in the browser. There is no install-time or background data collection outside your integration (initialize(), check(), and optional subscribe()).

Integrators are responsible for disclosing this behavior to end users and obtaining consent where required by applicable privacy law and your policies.

Distribution format

Published npm and GitHub Release artifacts are intentionally minified production bundles (safe-sdk.esm.min.js, safe-sdk.umd.min.js). Source maps are not included in the npm package.

Each GitHub Release includes SHA256SUMS for verifying bundle integrity.

License

Use of the SDK is governed by LICENSE.

Support

See Support in the integration guide.