Integration guide

Ship in minutes

Add ShieldPass to an existing project with a script tag or @shieldpass/sdk. Send the token to your backend and verify with your site secret — no captcha infrastructure to run.

Overview

ShieldPass is privacy-first with adaptive friction: the browser sends coarse passive signals to POST /api/v1/challenge. You get a numeric risk score and, when needed, a short mini-game challenge. After completion, POST /api/v1/complete returns a token. Your server always finishes with POST /api/v1/verify using your secret, never trust the browser alone.

When risk is high, the service randomly assigns one of three challenges: tap order, odd one out, or direction match. The embed widget handles UI for you; the SDK lets you render challenges in your own app if you prefer.

What we publish here. Public HTTP shapes and integration patterns only, not internal scoring formulas or signing internals.

Quick start

  1. Create an account and add a site in the dashboard. Copy your site key (public) and secret (server-only).
  2. Add the embed script to your page, or install @shieldpass/sdk in a React/Next app (see below).
  3. On form submit, read the token from the widget hidden field or SDK, then call POST /api/v1/verify from your backend with the secret.
  4. Only proceed with signup, checkout, etc. when verify returns success: true.

Dashboard & keys

CredentialWhere it livesPurpose
site keyBrowser, embed tag, SDKIdentifies your site to the hosted API. Safe to expose like a publishable key.
secretYour servers onlyVerifies tokens on /verify. Never put this in client code, front-end env vars, or public repos.

Each site has a hostname and allowed origins for browser calls. When you create a site, we suggest HTTPS origins from your hostname; you can edit them in the dashboard if you embed on multiple subdomains or staging URLs.

Never send the secret on /challenge or /complete. Only your backend calls /verify.

HTTP API

Base URL: https://shieldpass-verify.vercel.app. JSON bodies with Content-Type: application/json.

POST /api/v1/challenge

Called from the browser with your site key and a passive signals object (timing and coarse interaction aggregates). Use the hosted embed or @shieldpass/sdk to collect signals; do not hand-craft payloads.

{
  "siteKey": "<your site key>",
  "signals": { /* opaque aggregates from the official client */ }
}

Responses

  • Low risk: challengeRequired: false plus token and expiresAt (Unix ms).
  • High risk: challengeRequired: true, challengeId, riskScore, a redacted challenge stub (type only), and a short-lived renderToken. Full UI data is loaded via POST /api/v1/challenge/render with siteKey, challengeId, and renderToken (single-use per challenge). The response includes an interactionToken for step-by-step POST /api/v1/challenge/interact. Answers are validated on the server and are not returned in one JSON blob.

POST /api/v1/challenge/render

Returns full challenge UI fields for an active challengeId. Requires siteKey, renderToken from the matching /challenge response, and an allowed browser origin. Validation always happens server-side via /challenge/interact and /complete.

POST /api/v1/challenge/interact

Step-by-step challenge progress from the browser. Each request includes siteKey, challengeId, an action, and the current interactionToken from the previous response. Tokens rotate after every call; stale tokens are rejected.

Supported action values depend on challenge type (demo steps, taps, picks, etc.). Use the embed widget or SDK; custom clients must follow the same flow the official client uses.

Do not skip this endpoint. Posting a guessed answer directly to /complete will not mint a token unless the server has already recorded a valid solve for that challengeId.

POST /api/v1/complete

Called from the browser to finalize a challenge after the user finishes the mini-game and the server has marked the session solved via /challenge/interact.

{
  "siteKey": "<your site key>",
  "challengeId": "<uuid>",
  "solution": { "type": "tap_order", "sequence": [] }
}

The solution.type must match the active challenge. For interactive types, the server checks Redis progress from /interact, not answer fields in this body. Prefer the embed or SDK instead of building custom complete payloads.

Success: token and expiresAt. Each challenge id is single-use.

POST /api/v1/verify

Called from your server only with the secret and the token from the client.

Enforced. Browser fetch with an Origin header is rejected with 403 so the secret cannot be used from client-side JavaScript.
{
  "secret": "<your secret>",
  "token": "<token from widget or SDK>"
}

Check success in the JSON body. On success you typically receive riskScore and interactiveCompleted (whether a mini-game ran).

Embed widget

Recommended for HTML forms and static sites. Load our hosted script, add a <shield-pass> element with your site key, then verify the token on your server. The bar is about 300px wide; when a challenge is required, it opens in an overlay iframe on your page (not inside the thin bar).

<script src="https://shieldpass-verify.vercel.app/sdk/shieldpass.js" async defer></script>

<shield-pass sitekey="YOUR_SITE_KEY" callback="onShieldPass"></shield-pass>

<script>
  function onShieldPass(token) {
    // Token ready, enable submit or stash for form POST
  }
</script>

<form method="post" action="/your-backend/signup">
  <shield-pass sitekey="YOUR_SITE_KEY"></shield-pass>
  <button type="submit">Sign up</button>
</form>

Programmatic API (global shieldpass after the script loads):

const id = shieldpass.render("#widget", {
  sitekey: "YOUR_SITE_KEY",
  callback: (token) => console.log(token),
  // optional; defaults to the script's origin (https://shieldpass-verify.vercel.app)
  "api-base": "https://shieldpass-verify.vercel.app",
});

shieldpass.getResponse(id);
shieldpass.reset(id);
shieldpass.remove(id);

On submit, read the hidden input shieldpass-response (or getResponse()) and verify server-side. Legacy div.shieldpass containers still auto-mount.

Try it: Live demo runs the same widget against the hosted API.

Widget theming

Customize embed appearance per site from the dashboard Widget theme panel. Styling uses allowlisted presets and CSS variables only, no custom CSS or JavaScript, so theming cannot affect challenge answers, tokens, risk scores, or verify results.

Dashboard (authoritative)

Saved themeConfig includes preset, mode, accent color, radius, shadow, animation, and brand label. The embed iframe loads this via GET /api/v1/theme?siteKey=… (origin must be allowed). New sites default to the default preset (dark + teal accent). Use shieldpass for a glass panel closer to the marketing lab widgets, or enterprise for light B2B forms.

HTML attributes (optional overrides)

Client-side styling overrides only. Server theme still applies for brand label and defaults.

<shield-pass
  sitekey="YOUR_SITE_KEY"
  preset="default"
  theme="dark"
  accent="#2dd4bf"
  radius="12"
  shadow="soft"
  animation="smooth"
></shield-pass>

JavaScript render options

shieldpass.render("#widget", {
  sitekey: "YOUR_SITE_KEY",
  preset: "shieldpass",
  theme: "dark",
  accent: "#2dd4bf",
  radius: 12,
});
Security. Theme data is validated server-side. Injection-like strings are rejected. Challenge flow, nonces, and tokens are unchanged.

CDN (Vercel Edge)

The embed script is a static bundle on our Vercel deployment. Every production deploy publishes it to the Vercel Edge Network (global CDN), no separate CDN project required. Load it from your ShieldPass origin or from a custom domain pointed at the same Vercel project (for example cdn.example.com).

ChannelURLWhen to use
latesthttps://shieldpass-verify.vercel.app/sdk/shieldpass.jsDefault, picks up new widget releases after cache refresh (~1 hour).
pinnedhttps://shieldpass-verify.vercel.app/sdk/v0.1.0/shieldpass.jsImmutable v0.1.0 path; long-lived browser cache. Pin in production when you want controlled upgrades.
<!-- Latest (default) -->
<script src="https://shieldpass-verify.vercel.app/sdk/shieldpass.js" async defer></script>

<!-- Pinned release -->
<script src="https://shieldpass-verify.vercel.app/sdk/v0.1.0/shieldpass.js" async defer></script>

Release manifest: https://shieldpass-verify.vercel.app/sdk/version.json. Versioned files are built from packages/sdk on each deploy (pnpm build).

Custom CDN hostname: in the Vercel project for this app, add a domain such as cdn.yourbrand.com, then use https://cdn.yourbrand.com/sdk/shieldpass.js. The script infers its API origin from the script URL unless you set api-base on the tag.

Browser SDK

For React, Next.js, or custom UIs. The SDK calls /challenge and /complete for you. If you do not use the embed widget, implement onChallenge to show the mini-game when required.

import { createShieldPassClient } from "@shieldpass/sdk";

const client = createShieldPassClient({
  siteKey: "YOUR_SITE_KEY",
  apiBase: "https://shieldpass-verify.vercel.app",
});

const { token, riskScore, challengeRequired } = await client.obtainToken({
  onChallenge: async (challenge) => {
    // challenge.type is tap_order | odd_one_out | direction_tap
    return await showChallengeUI(challenge);
  },
});

client.dispose();

Point apiBase at the hosted origin unless you are developing against a local ShieldPass instance. The secret never belongs in this code path.

Allowed origins

Browser calls to /api/v1/challenge and /api/v1/complete must come from origins registered for your site in the dashboard. We derive suggested origins from your hostname when you create a site; add staging or marketing domains if needed.

In local development, localhost and 127.0.0.1 on the same port are treated as equivalent.

/verify is not callable from the browser, no CORS policy applies because requests with an Origin header are blocked.

Limits & TTL

  • Tokens are short-lived (on the order of two minutes), verify soon after issuance.
  • Challenges expire in a similar window and cannot be reused after a successful complete.
  • Rate limits protect the public endpoints; retry after backoff if you receive 429.

Errors

StatusMeaning
400Invalid JSON or body shape; expired or already-used challenge.
403Invalid site key or secret; origin not allowed; or /verify called from a browser.
429Rate limit exceeded.
503Service temporarily unavailable, retry with backoff.

JSON error bodies include an error string when applicable.

Privacy

ShieldPass collects aggregated passive signals to compute a risk score. We do not read your form fields, passwords, or payment data.

Challenge state and rate-limit data are kept only as long as needed (short TTLs). Tokens are signed assertions for your backend to verify, not long-term user profiles.

The embed iframe is served from the ShieldPass origin; footer links on the widget point to this policy.

Terms

By using ShieldPass, you agree to use it for lawful bot mitigation on properties you control or are authorized to protect.

  • Do not attempt to reverse engineer, bypass, or resell the service without permission.
  • Do not use ShieldPass to collect sensitive personal data beyond the signals described in Privacy.
  • You are responsible for informing end users as required by your jurisdiction.
  • Maintain your own fallback if verification is business-critical.

Security

ShieldPass uses layered server-side checks (risk scoring, challenge progress, rate limits, token binding, and more). We do not publish thresholds, signal weights, or validation rules. Assume motivated attackers can read client code and network traffic.

  • Store the secret in a secret manager; rotate from the dashboard if it leaks.
  • Verify every sensitive action with /verify, never trust the client alone.
  • Use HTTPS between your users, ShieldPass, and your backend.
  • Use the hosted embed or official SDK for challenges. Do not document or depend on posting raw answers to /complete.
  • Treat riskScore as advisory; enforce your own business rules on verify.