Documentation
Protect pages and the data they load.
Install Stopnetic on the server that sends the content. Verify a browser on a page, then require that session before returning protected API data. Your frontend can use Next.js, React, Vue, Angular or plain JavaScript.
Start here
- Create an account, verify your email, and choose the 3-day trial for one website or a paid plan.
- Add the hostname that serves your content. Verify domain ownership and create its private installation key in Integration.
- Save the Site ID, service URL, installation key, public decision key and a separate random cookie secret in your website server's environment. Keep secrets out of browser JavaScript.
- Install the server guard, build and deploy. Run the connection test with deployed settings to report coverage.
- Save page and API rules in Policies. Test a fresh browser session and direct API requests.
The free trial starts with the first protected request, lasts 72 hours and does not charge automatically. After expiry, paid protection is required. Verification is a browser-session check; capable automated browsers may complete it. Keep your own login and data permissions.
Open installation settingsInstall with your coding agent
Download the guide for your project and attach it to your coding agent. It explains how to add Stopnetic while preserving your existing application.
Next.js 16 App Router
Guided setup, existing Proxy files, protected APIs and deployment checks.
Download Next.js guide (.md)JavaScript / Node.js
Node, Express and supported SSR or static apps on compatible server hosting.
Download JavaScript guide (.md)Message to your agent: Follow the attached Stopnetic guide to integrate it into this project. Preserve the existing app, review conflicting files and verify the protected pages and APIs.
These guides contain no account credentials. Add your site settings separately to your project's private server environment and hosting settings.
Pages and APIs work together
A page is opened by browser navigation. An API supplies JSON or other data to fetch, XMLHttpRequest or another client. Protect both: restricting a page alone leaves its data endpoints reachable.
Example: a membership website has a /members page that loads a profile and order history from its APIs. These are sample paths for illustration. Replace them with the routes in your own application when creating rules in Policies.
1. Open the protected page
2. Browser verification creates a cookie
3. Fetch sends the cookie to the protected API
| Path | Type | Action |
|---|---|---|
| /members | Page | Automatic browser flow |
| /api/members/profile | API | Require verified session |
| /api/members/orders | API | Require verified session |
For this example, save the three rules, then open /members on the website. A fetch request cannot execute the browser verification page; without an existing session the protected API returns 404. The same-origin browser request sends its cookies:
// Example: load profile data from the /members page.
const response = await fetch('/api/members/profile', {
credentials: 'same-origin',
headers: { Accept: 'application/json' },
cache: 'no-store',
});
if (!response.ok) throw new Error('Request failed: ' + response.status);
const profile = await response.json();More example route rules
A shop can protect its catalogue page and product APIs, keep its pricing page public, and block internal routes. Use only the examples that fit your website.
| Path | Type | Action |
|---|---|---|
| /catalog | Page | Automatic browser flow |
| /api/catalog/* | API | Require verified session |
| /pricing | Page | Public |
| /internal/* | Custom / mixed | Block |
Choose Page, API or Custom / mixed in the rule editor. Existing rules suggest a type from the path; override it for APIs such as /graphql or /v1/products. Selecting API converts an automatic browser action to Require verified session. Type describes the rule; it does not inspect traffic or share sessions across domains. Actual method, headers, session and action still determine access.
Rules contain paths on the selected site, not full URLs. First match wins. /api/catalog/* covers children such as /api/catalog/products; /catalog is exact. Move specific exceptions above broader rules. Public permits unverified clients too. Block returns 404 even with a valid session. Whole-site mode leaves unmatched routes public; selected-path mode blocks unmatched requests only where its guard runs.
Configure route rulesPrivate client previews
Send your client a normal website link and a shared password. They unlock the preview without creating an account. In Policies, choose Private client preview, select Whole website or Selected pages and routes, set a password and save.
// Add to your existing compatible server guard configuration:
passwordProtection: true,Deploy the compatible service and SDK first. Whole website requires whole-site guard coverage. For selected paths, use one path per line, such as /preview/* and /api/preview/*. Include the private APIs, files and downloads the page uses. Files or other hosts outside your guard remain public; avoid placing private data in public build assets and clear previously public caches.
Unlocks last up to 12 hours in the same browser. Saving preview settings revokes earlier unlocks; changing the password relocks previous visitors. Passwords are stored as salted hashes. Five unlock attempts per site per minute share an allowance, including correct attempts. A client with the password can share it.
The prompt is a separate document returned before private content. Direct API calls receive an empty 401 until unlocked. Existing block, verification, country and account rules still apply after unlocking. Missing setup returns 503 and withholds the content.
Configure private previewOptional interactive verification
In Route rules, choose Interactive browser flow (checkbox) for a page. Visitors select Verify to continue before the existing server check runs. Automatic mode remains available. Automated browsers can complete this flow; the checkbox does not prove human identity.
// Add to your existing compatible server guard configuration:
interactiveVerification: true,Deploy the compatible service and SDK before enabling. For related APIs, select Require verified session and enable Require a session from the interactive flow. A session created by automatic verification cannot satisfy this requirement. API requests cannot display a checkbox themselves.
Confirmations are tied to a short-lived, single-use challenge and checked before content is sent. Existing access rules, work checks and budgets still apply. Missing support withholds access. A password-protected client preview still needs its separate password.
Next.js 16 App Router
Requires Next.js 16 App Router and Node.js 20.9 or newer.
Using Next.js 14 or 15? Upgrade your application before running Stopnetic setup. The installer stops on unsupported versions; installing the package alone does not enable protection.
How to upgrade to Next.js 16
Save your work in Git, check your Node.js version, then run the official upgrade tool in your application directory. Review its changes and resolve migration issues before continuing.
node --version npx @next/codemod@canary upgrade 16 # If the app still uses synchronous request APIs: npx @next/codemod@canary next-async-request-api . npm run build
Run your application's tests and check its pages after upgrading. Pages Router apps also need an App Router integration. Once the app works on Next.js 16 App Router, continue with the Stopnetic installation commands below.
Official Next.js 16 upgrade guideInstall the Next.js package inside your website project after saving the server settings from Integration. Whole-site setup generates a Proxy, guard and verification endpoint:
npm install @stopnetic/next
npm exec --no -- stopnetic-next init --site --dry-run
npm exec --no -- stopnetic-next init --site
npm exec --no -- stopnetic-next check
npm exec --no -- stopnetic-next test-connection --productionSave the same settings in your host, build and deploy once. Ordinary rule edits then apply on the next guarded request without another npm install or deployment. Existing installations upgrade and migrate with update-coverage --site; preview with --dry-run first. Customized Proxy files need manual merging.
The verification endpoint /api/stopnetic/verify belongs to Stopnetic and is separate from your application's pages. Keep the verification endpoint excluded from interception. Check authorization before protected Route Handlers and Server Functions return data. A server-side fetch does not inherit browser cookies automatically; authorize the incoming request before returning its result.
JavaScript hosting and installation
Examples use https://www.example.com. Replace it with your own website's origin when configuring your installation.
Choose how your existing app renders, then its SSR framework and hosting. Angular, React Router, React custom SSR, Nuxt, Vue custom SSR, SvelteKit, Astro, SolidStart and other Node servers have specific instructions below. Browser-only apps use the static option. Node.js 22 or newer is required. These selections change the guide, not your site or plan.
Two rendering options: preserve SSR by checking access before the existing Node renderer, or retain a static/browser app with a server check before HTML. Choose the app's current mode. Keep SSR files, hydration, routes and features. A function serving index.html is static page handling, not SSR. A prerendered page is static output.
Policies decide which pages need verification. If only /members is protected, unmatched /about and /contact stay public. A server policy check does not protect every page. Keep browser startup and layout unchanged for document navigation; do not add a global Checking access... screen or copy demo rules into the dashboard. Public requests still need a valid signed decision; service failures withhold content.
Select the app's existing rendering to view installation code. If it runs SSR at the Edge, the current Node SDK needs a separate supported runtime or gateway decision. Do not change rendering automatically.
A host's default subdomain may not let you add DNS TXT records, so use a domain you control for normal production setup. Hosting selection does not waive domain verification.
After setup and deployment, ordinary policy edits apply on the next guarded request without npm updates or redeployment. Private data belongs in guarded APIs. Public bundles and already loaded content stay accessible, and capable automated browsers can complete verification.
When the API is on another domain
Recommended: a server endpoint on your website
For example, have a shop's browser call /api/remote-products on the same origin. Its guarded server handler checks the browser session, then fetches the remote API using a separate server-only application credential. Return only the permitted data with private, no-store caching. This works with a Next.js Route Handler or a Node/Express handler.
Browser → /api/remote-products
Website guard → authorized server handler
Server handler → private remote API
Keep the upstream URL fixed in server configuration and restrict the upstream using its own authentication or network controls. A proxy does not protect an independently public upstream. Do not send the Stopnetic installation key or browser cookie to the remote API. This architecture needs application-side wiring; adding a dashboard rule does not create a proxy.
Next.js server proxy example
Application template: configure a fixed PRODUCTS_UPSTREAM_URL and its separate PRODUCTS_UPSTREAM_TOKEN on your server. Adjust the import and user permissions for your app. Protect /api/remote-products with Require verified session and the calling /catalog page with Automatic browser flow.
// app/api/remote-products/route.js (adjust import for src/app)
import { stopnetic } from '../../../stopnetic.guard.js';
const fail = status => new Response(null, {
status, headers: { 'cache-control': 'private, no-store' },
});
export async function GET(request) {
try {
const blocked = await stopnetic().check(request);
if (blocked) return blocked;
} catch { return fail(503); }
// Also enforce your application's user/data permissions.
const url = process.env.PRODUCTS_UPSTREAM_URL;
const token = process.env.PRODUCTS_UPSTREAM_TOKEN;
if (!url || !token) return fail(503);
try {
const target = new URL(url);
if (target.protocol !== 'https:' || target.username || target.password) {
return fail(503);
}
const upstream = await fetch(target, {
headers: { Authorization: 'Bearer ' + token, Accept: 'application/json' },
cache: 'no-store', redirect: 'error', signal: AbortSignal.timeout(5000),
});
if (!upstream.ok) return fail(502);
return Response.json(await upstream.json(), {
headers: { 'cache-control': 'private, no-store' },
});
} catch { return fail(502); }
}Advanced: direct browser fetch to the API host
Protect that API server separately, verify its hostname and configure its own site/key/guard. Establish verification on an HTML page served by that API origin first. The SDK uses host-only, installation-bound cookies: verification on www.example.com is not automatically valid on api.example.com. Reusing a cookie secret does not bridge sessions.
Cross-origin requests need credentials: 'include' and an explicit allowed frontend origin with credentialed CORS responses. Handle permitted OPTIONS preflights without exposing data and enforce the guard on the actual request. Unrelated-site cookie policies can still prevent access; the current SDK uses SameSite=Lax and does not provide a cross-site session bridge.
CORS controls browser access to responses; it does not authorize clients or block direct requests. This direct-domain setup is not an automatic or validated turnkey integration. Use the same-origin server approach when possible.
Fetch credentials referenceCORS referenceCookie scope reference
Optional country and device insights
Overview and Event explorer can show country/device estimates reported by a compatible server guard. Existing SDK 0.1.0 installations do not send these fields and appear as Unknown. Updating only the Stopnetic dashboard cannot enrich old requests.
With an SDK release that supports traffic insights, set trafficInsights: true in createStopnetic. Set countrySource to 'vercel' only on a trusted Vercel ingress, or 'cloudflare' only when your origin prevents direct access or strips and replaces visitor-supplied country headers. The default 'none' collects no country. No provider is inferred from incoming headers.
// Add to your existing createStopnetic configuration on your server:
trafficInsights: true,
countrySource: 'none', // or a configured trusted 'vercel' / 'cloudflare' ingressThe JavaScript server helper also accepts STOPNETIC_TRAFFIC_INSIGHTS=true and STOPNETIC_COUNTRY_SOURCE=none in your website's server environment. For an existing generated Next.js guard, add the options above explicitly. Build and deploy your website after updating the SDK or its configuration.
The guard sends only a country code/source and a broad device category. It does not send raw IP addresses or full user-agent strings for these insights, and performs no external location lookup. VPNs and spoofed client headers affect accuracy. Missing or ambiguous information stays Unknown. These fields do not change access rules or identify a person or bot.
Breakdowns count reported allowed, challenged and blocked requests, excluding verification-only observations. Event explorer can also show observations. Requests are not unique visitors or invoice counters. Country/device filters are available in Event explorer; Excel requires an active Growth or Ultimate plan. Insight records follow the same history/deletion behavior as their events; the dashboard history window is not a physical deletion schedule.
Limit data and action units
Use a verified-session rule for the API or action. Your server defines a unit, such as one catalog record or one expensive operation. Add a requestCost callback to your guard, enable trusted Vercel network protection in block mode, then enable the data budget in Policies. Choose the maximum units per minute and immediate burst capacity.
// Add to your existing SERVER guard options.
botProtection: 'block',
botClientSource: 'vercel',
requestCost(request) {
const url = new URL(request.url);
if (url.pathname !== '/api/catalog') return null;
// Validate once with shared application code; reject duplicates/out-of-range.
return validatedCatalogLimit(request);
}Use that same validated limit in the database query and enforce it on returned records. The callback receives URL, method and headers, with no request body, only after local session validation. Return null for unmetered routes or a positive integer up to 1,000,000. A visitor-provided cost header or body flag is not trusted. Never fetch or release the data before the guard check finishes.
For example, a burst capacity of 500 permits one 500-record request or five 100-record requests before refill. A request larger than capacity is rejected. Missing cost, policy, trusted network context or compatible signed service support returns 503; exhausted capacity returns an empty 429, with Retry-After when refill can admit the request. A verified session does not bypass the budget. Apply one charging check per request, rather than checking again in both Proxy and the handler.
Reservations share the canonical rule and network allowance across wildcard paths, methods, new cookies and server workers. Shared networks can affect legitimate visitors; changed networks can obtain a different allowance. A reserved request that later fails still consumes units. Public routes are not metered. This limits configured resource use and does not identify AI or prevent every slow or distributed scraper. Initial support requires trusted Vercel ingress; self-hosted network sources are not supported.
Limit repeated requests
On protected browser or verified-session rules, enable Limit repeated requests in Policies. Choose a continuous rate and a burst allowance, then save. For example, 12 requests per minute with a burst of 3 allows three immediate requests, then one every five seconds. Existing site limits also apply.
First configure and deploy the website's server guard on trusted Vercel ingress using an SDK that supports network protection:
// Add to your existing server-only createStopnetic options:
botProtection: 'block',
botClientSource: 'vercel',Deploy the updated Stopnetic service to all serving instances before enabling limits. Without the required network metadata or block mode, limited routes become unavailable (503). Network controls currently require Vercel; they do not accept arbitrary forwarding headers. The guard keeps raw IP addresses on the website server and reports a scoped daily network group.
Requests share the budget across a rule's wildcard paths, methods, cookies and verified sessions. New browser sessions do not reset it. A page's first check and verified reload both count. People sharing a network can share a budget, so allow normal page and API bursts. Public routes cannot have budgets.
Exceeding a budget returns an empty 404 with request_rate evidence. Disabling the limit takes effect on the next request. Preview does not simulate live counters. These controls limit repeated abuse; they do not prove human identity or stop every first-visit agent.
Pause sustained overuse
Policies can also pause a network across protected routes after repeated request-budget denials in a fixed 60-second counting window. This is off unless enabled. Choose 5–100 denied requests and a pause of 30–900 seconds; the editor initially suggests 10 denials and 60 seconds.
Requests during a pause do not extend its expiry. Public routes remain accessible, but verified sessions and pending verification cannot bypass a pause. Disable this setting and save to stop enforcing it immediately. Re-enabling before expiry restores the same pause.
The same trusted Vercel network setup and block mode are required for all protected routes when pauses are enabled. Missing support makes them unavailable (503). People sharing a network can be paused together; configure limits according to normal use. Changing actual networks can evade the pause. Event explorer records network_cooldown with its fixed expiry, without raw IP addresses or a human/AI identity claim.
Country access controls
Requires the upcoming compatible SDK release; published 0.1.0 does not support country controls. Update the service first, then install the compatible SDK. On your server, add countryBlocking: true and countrySource: 'vercel' or 'cloudflare' to createStopnetic options. The JavaScript server environment helper also reads STOPNETIC_COUNTRY_BLOCKING=true and STOPNETIC_COUNTRY_SOURCE. Remove local publicPaths bypasses.
Your hosting ingress must overwrite visitor-supplied country headers. For Cloudflare, enable its country header and prevent direct origin requests. Test a guarded request with every active installation key. In Policies, select blocked countries and choose whether Unknown continues normal route rules or blocks. Save country settings to activate. All active keys need a country-ready request within 24 hours when enabling or changing an enabled policy; this is a configuration report, not proof of whole-site coverage.
Country checks run before public route rules and verified sessions, and again during verification. Blocked requests receive an empty 404. If an enabled policy receives no country-capable request, it blocks even if Unknown is allowed. Unsupported service responses fail closed with 503. Geography is approximate and VPNs can change it. Static files, routes without a guard, local exclusions and responses served from an earlier CDN cache are outside coverage. Prevent those bypasses for any content requiring country controls.
Recover through this separate dashboard: disable country blocking, or restore previous selections in the same editing session and save. The event inspector includes the policy revision, country reason and configured source; no raw IP or user-agent is sent. Country enforcement sends its country/source even when optional traffic insights are off. Historical estimates count reported access checks rather than visitors.
Testing and errors
- API returns 404: protect and reload its calling page first; confirm the cookie uses the same hostname and current installation. After the short session expires, reload the protected page to verify again. Check rule order, exact path, credentials and reported coverage.
- Blank React page: inspect DevTools Network for JS/CSS URLs returning HTML. Preserve asset routing and MIME types; the Netlify page function must include its public asset files.
- Signing verification keys must be public PEMs: copy the full public decision key, including BEGIN/END lines, with real newlines or literal \n. Hosting fields use no surrounding quotes; quote the value in a local .env file. Redeploy after changing hosted values.
- 503: check server environment values, signing trust, service availability, domain proof and plan status. The guard withholds data when it cannot authorize access.
- Network/CORS error: inspect DevTools Network and the API server response. A blocked cross-origin response may appear as a fetch error rather than exposing its HTTP status.
- A saved block seems ineffective: make a new request. Previously loaded data is not recalled. Check CDN/service-worker caching and whether the deployed guard covers that route.
- Preview a request: simulation only. Its path/session/outage fields are not saved or sent to your website. Only Route rules control live requests. Unknown coverage uses a stated assumption.
Test with a fresh browser, a verified browser, direct unverified API requests, block/public changes and an unavailable service. Overview and Event explorer show reported outcomes. Verification does not replace user login, membership checks or protection against capable browser automation.
