Integration Guide

Complete walkthrough for integrating ZXERO protection and monetization into your site.

1. Install the Tag

Add this single script tag to your HTML <head> or before </body>:

<script
  src="https://cdn.zxero.dev/firewall.umd.js"
  data-site-key="site_xxx"
></script>

Replace site_xxx with your actual site key from the dashboard.

2. Server-side Enforcement

The script sends a signed zx_token cookie. Verify it on your backend to enforce protection.

Nginx

location / {
    # Extract zx_token cookie
    set $zx_token "";
    if ($http_cookie ~* "zx_token=([^;]+)") {
        set $zx_token $1;
    }

    # Check if valid (call ZXERO verify endpoint)
    auth_request /zxero_verify;
    auth_request_set $auth_status $upstream_status;

    # Proceed if verified
    proxy_pass http://your_backend;
}

location = /zxero_verify {
    internal;
    proxy_pass https://api.zxero.dev/api/v1/verify?token=$zx_token&site_key=site_xxx;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
}

Express (Node.js)

const express = require('express');
const axios = require('axios');
const app = express();

const ZXERO_API = 'https://api.zxero.dev/api/v1';
const SITE_KEY = 'site_xxx';

async function verifyZxToken(token) {
  try {
    const res = await axios.get(`${ZXERO_API}/verify`, {
      params: { token, site_key: SITE_KEY }
    });
    return res.data.valid === true;
  } catch {
    return false;
  }
}

// Middleware
app.use(async (req, res, next) => {
  const token = req.cookies.zx_token;

  if (!token) {
    return res.status(403).json({ error: 'Missing zx_token' });
  }

  const valid = await verifyZxToken(token);
  if (!valid) {
    return res.status(403).json({ error: 'Invalid zx_token' });
  }

  next();
});

app.listen(3000);

Cloudflare Worker

addEventListener('fetch', event => {
  event.respondWith(handleRequest(event.request));
});

const ZXERO_API = 'https://api.zxero.dev/api/v1';
const SITE_KEY = 'site_xxx';

async function verifyZxToken(token) {
  try {
    const url = `${ZXERO_API}/verify?token=${token}&site_key=${SITE_KEY}`;
    const res = await fetch(url);
    const data = await res.json();
    return data.valid === true;
  } catch {
    return false;
  }
}

async function handleRequest(request) {
  const cookie = request.headers.get('Cookie') || '';
  const match = cookie.match(/zx_token=([^;]+)/);
  const token = match ? match[1] : null;

  if (!token) {
    return new Response('Missing zx_token', { status: 403 });
  }

  const valid = await verifyZxToken(token);
  if (!valid) {
    return new Response('Invalid zx_token', { status: 403 });
  }

  // Pass through to origin
  return fetch(request);
}

3. Crawler Access (Buyer Flow)

Legitimate crawlers (AI trainers, researchers, archivists) purchase API keys via Stripe Checkout.

How it works:

  1. 1. You generate a checkout link from your dashboard with the buyer's email and amount.
  2. 2. Buyer pays via Stripe and receives an API key instantly.
  3. 3. Buyer makes requests by passing the API key in the X-ZXERO-Key header.
  4. 4. You verify the key server-side via the /verify_api_key endpoint.

Example: Buyer makes a request

curl https://yoursite.com/api/data \
  -H "X-ZXERO-Key: zxk_abc123xyz"

Example: Your server verifies the key

const apiKey = req.headers['x-zxero-key'];

const res = await axios.get('https://api.zxero.dev/api/v1/verify_api_key', {
  params: { api_key: apiKey, site_key: 'site_xxx' }
});

if (res.data.valid) {
  // Allow access
  const rateLimit = res.data.rate_limit_rps; // e.g. 5.0 req/sec
  // Apply rate limiting logic
} else {
  // Deny access
  return res.status(403).json({ error: 'Invalid API key' });
}

4. Analytics & Quotas

Plan Limits

  • Free: 10,000 events/month
  • Pro: 100,000 events/month
  • Enterprise: 1M+ events/month (custom)

An "event" is any decision request (bot check, API key verification, or checkout creation).

View Analytics

Get real-time metrics via the dashboard or programmatically:

GET https://api.zxero.dev/api/v1/analytics/overview?site_key=site_xxx
Authorization: Bearer <your_token>

Response:
{
  "total_events": 8432,
  "total_decisions": 8200,
  "human_decisions": 7890,
  "bot_decisions": 310,
  "api_key_checks": 232,
  "quota_remaining": 1568,
  "monthly_quota": 10000
}

Timeseries Data

GET https://api.zxero.dev/api/v1/analytics/timeseries?site_key=site_xxx&days=7
Authorization: Bearer <your_token>

Response:
{
  "data": [
    { "date": "2025-10-24", "events": 1203, "human": 1150, "bot": 53 },
    { "date": "2025-10-25", "events": 1289, "human": 1220, "bot": 69 },
    ...
  ]
}

5. Security & Best Practices

Token Security

  • HMAC-signed tokens: Every zx_token is signed with your site secret. Replay attacks are prevented by short TTL (5 minutes).
  • Server-side verification only: Never trust client-side checks. Always verify tokens on your backend.
  • HTTPS required: All API calls and token exchanges must use HTTPS.

Rate Limiting

API keys include a rate_limit_rps value (requests per second). Enforce this on your backend using:

  • Token bucket algorithm
  • Redis for distributed rate limiting
  • Nginx limit_req module

Privacy & Compliance

  • ZXERO never stores your site content
  • Only metadata (timestamps, decisions, quotas) is logged
  • GDPR-friendly: No PII collected from end users
  • Audit logs available for Enterprise plans

Next Steps

Go to Dashboard→Quick Start Guide→Contact Support→Privacy & Compliance→