Install AI Protection

Beta release

Start with an owned test endpoint and observation mode. Pin the Beta package version when deploying and review changes before upgrading.

1. Select your application and create a key

Open AI Protection and select the property for your application. Copy the property ID from Connect this application.

In API keys, create a key scoped to that property with Write Detections permission. Store the key in your server’s secret configuration. Never include it in browser JavaScript or a mobile client.

2. Install the SDK in your backend

Node.js / Next.js

Requires Node.js 22.22.3 or newer.

npm install @webdecoy/[email protected]

Follow the Next.js integration guide for the route wrapper, trusted client IP, and streaming lifecycle.

Cloudflare Workers · experimental

Install @webdecoy/[email protected] (the adapter is available from alpha.13) and follow the Workers setup guide with Node compatibility enabled. It supports admission, local rules, shared quotas and reporting; concurrency and budgets are not supported. Create a new protection object for each request inside fetch().

Go

Requires Go 1.26.1 or newer.

go get github.com/WebDecoy/[email protected]

Follow the Go integration guide.

Python / FastAPI

Requires Python 3.11+ and asyncio.

python -m pip install 'webdecoy-ai-protection[fastapi]==0.1.0b1'

Omit [fastapi] for the core async client. Follow the FastAPI integration guide. The repository includes a deterministic local streaming example that does not call a paid model.

3. Configure the connection

Use https://ai-protection.webdecoy.com as the SDK base URL. This is an API endpoint; opening its root in a browser may return 404. Customers do not need to deploy this service or configure a custom DNS record.

Setting	Node.js	Go	Python
Base URL	webdecoyUrl	BaseURL	base_url
Property ID	propertyId	PropertyID	property_id
Server API key	webdecoyKey	APIKey	api_key
Observation mode	protectionMode: 'observe'	Mode: protection.Observe	mode="observe"

For Node.js, Go and Python, create one shared client per application process and reuse it. The Workers adapter requires one protection object per incoming request. Use a fixed route template such as /api/chat, not a raw URL containing user IDs or query strings. Derive client IP from your trusted ingress configuration; do not trust arbitrary forwarded headers.

4. Wrap the AI route

Integrate after authentication, authorization, and input validation, immediately before the model would run:

1. Pass trusted server context into local rules and optional account controls.
2. Ask the SDK for admission, or use the framework wrapper that enforces the decision.
3. Start inference only when admitted. Defer the model call inside the protected callback.
4. Propagate cancellation to the provider. Keep concurrency leases active until all protected work and streaming finish.
5. Report the application outcome. For budgets, wrap each individual model attempt and provide confirmed final usage when available.

Use the SDK-specific guide for executable code: the wrappers and completion hooks differ by runtime. Quotas, concurrency, and budgets are opt-in integrations; installing the package or changing the dashboard detector mode does not activate them.

5. Verify, then enable enforcement

Send an authenticated test request and refresh AI Protection. Check that a stored AI check and application decision appear for the correct property. A successful HTTP response alone does not prove cloud protection was available: inspect degraded coverage too.

Keep cloud detector failures allowed through initially. If WebDecoy detection is unavailable, legitimate requests can continue with degraded coverage; local application rules keep their own policies.

For Node.js, scripts/doctor-model.mjs in the SDK source runs these checks for you in-process: allowed and denied requests, a detector block, streaming, cancellation, an outage and budget settlement, against a stand-in WebDecoy runtime and a stub model provider. It never calls a paid model, and its report lists what it did not exercise.

After reviewing results, enable cloud enforcement in both the SDK and the dashboard, if your account permits it. Configure quota, concurrency, and budget modes separately. Use the verification checklist before expanding the rollout.

MCP servers (Node.js)

If your AI feature exposes tools over MCP (Streamable HTTP), serve them through the SDK’s MCP adapter. Each tool call is authenticated, checked against your per-tool authorization and optional work limits, and only then runs. The setup commands run from an SDK source checkout and never execute your project’s code to inspect it.

1. Find your layout. node scripts/doctor-mcp.mjs detect /path/to/app reports whether the project is supported (TypeScript Node ESM HTTP servers are), names your mcpOptions module and route file, lists MCP servers whose tools bypass WebDecoy, and prints the next commands with your files filled in.
2. Generate and wire the handler. setup-mcp.mjs and wire-mcp-route.mjs each have a plan mode that changes nothing, an apply that is safe to repeat, and a rollback that refuses to remove anything you edited.
3. Check the running route. Write a plan naming synthetic test callers and the calls you expect to be allowed, forbidden or refused as cross-tenant, then run doctor-mcp.mjs check plan.json. Tokens are read from environment variables you name and never printed. A refusal for the wrong reason fails the check.
4. Check an outage. Add outageRuntime to the plan and point a local copy of your server at the stand-in runtime it serves. Closed limits must refuse with 503, open ones must keep working, and your own authorization must still hold. If the server never consulted the stand-in, the results are reported as inconclusive rather than passing.
5. Find the action in the dashboard. From alpha.19, every tool result carries _meta["webdecoy.com/action"].actionId. The check report links the first one: https://app.webdecoy.com/ai-protection?property=<property ID>&action=<action ID> shows every reported phase of that call.

The full command reference is in the SDK’s MCP setup guide.