Integration guide
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.
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.
@shieldpass/sdk in a React/Next app (see below).POST /api/v1/verify from your backend with the secret.success: true.| Credential | Where it lives | Purpose |
|---|---|---|
site key | Browser, embed tag, SDK | Identifies your site to the hosted API. Safe to expose like a publishable key. |
secret | Your servers only | Verifies 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.
/challenge or /complete. Only your backend calls /verify.Base URL: https://shieldpass-verify.vercel.app. JSON bodies with Content-Type: application/json.
POST /api/v1/challengeCalled 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
challengeRequired: false plus token and expiresAt (Unix ms).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/renderReturns 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/interactStep-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.
/complete will not mint a token unless the server has already recorded a valid solve for that challengeId.POST /api/v1/completeCalled 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/verifyCalled from your server only with the secret and the token from the client.
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).
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.
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.
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.
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>
shieldpass.render("#widget", {
sitekey: "YOUR_SITE_KEY",
preset: "shieldpass",
theme: "dark",
accent: "#2dd4bf",
radius: 12,
});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).
| Channel | URL | When to use |
|---|---|---|
latest | https://shieldpass-verify.vercel.app/sdk/shieldpass.js | Default, picks up new widget releases after cache refresh (~1 hour). |
pinned | https://shieldpass-verify.vercel.app/sdk/v0.1.0/shieldpass.js | Immutable 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.
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.
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.
429.| Status | Meaning |
|---|---|
| 400 | Invalid JSON or body shape; expired or already-used challenge. |
| 403 | Invalid site key or secret; origin not allowed; or /verify called from a browser. |
| 429 | Rate limit exceeded. |
| 503 | Service temporarily unavailable, retry with backoff. |
JSON error bodies include an error string when applicable.
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.
By using ShieldPass, you agree to use it for lawful bot mitigation on properties you control or are authorized to protect.
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.
/verify, never trust the client alone./complete.riskScore as advisory; enforce your own business rules on verify.