Fastly - Supertab Connect docs

Supertab Connect integrates with Fastly for two purposes: serving your RSL license at /license.xml via your domain, and enforcing the Crawler Authentication Protocol (CAP) to protect content from unlicensed crawlers.

Publishing RSL License

Your RSL license needs to be accessible at https://yourdomain.com/license.xml. Fastly proxies this path to the Supertab Connect origin, keeping the URL on your domain. The configuration differs slightly between VCL and Compute services.

VCL Service

Add a backend pointing to the Supertab Connect origin, attach it to a condition that matches the license URL, and add a VCL snippet that rewrites the short path to the full URN path.

Backend

Add a new host with the following configuration:

Name:                 supertab-connect-backend
Address:              api-connect.supertab.co
Port:                 443
TLS:                  enabled
SNI hostname:         api-connect.supertab.co
Certificate hostname: api-connect.supertab.co
Override host:        api-connect.supertab.co

Condition

Attach a request condition to supertab-connect-backend:

req.url ~ "^/merchants/systems/YOUR_WEBSITE_URN/license\.xml(\?|$)"

VCL Snippet

Add a recv snippet at priority 100:

if (req.url.path == "/license.xml") {
  set req.url = "/merchants/systems/YOUR_WEBSITE_URN/license.xml";
}

This rewrites the short URL before the condition runs, so the backend condition matches and the request is routed to api-connect.supertab.co. Activate the new version once the backend, condition, and snippet are in place.

Compute (Wasm) Service

For Compute services, add a backend named supertab-connect-backend pointing to api-connect.supertab.co:443 with TLS enabled. The SDK handles URL rewriting and routing internally when enableRSL: true is set — no VCL condition or snippet is needed.

/// <reference types="@fastly/js-compute" />
import { SupertabConnect } from "@getsupertab/supertab-connect-sdk";
import { SecretStore } from "fastly:secret-store";

const secrets = new SecretStore("supertab_config");
const merchantApiKey = await secrets.get("MERCHANT_API_KEY"); // from your Supertab Connect dashboard

addEventListener("fetch", (event) => {
  event.respondWith(
    SupertabConnect.fastlyHandleRequests(
      event.request,
      merchantApiKey,
      "supertab-connect-backend",
      {
        enableRSL: true,
        merchantSystemUrn: "YOUR_WEBSITE_URN",
      }
    )
  );
});

CAP Enforcement

CAP validates the Authorization: License <token> header on crawler requests, verifying that the crawler holds a valid license before allowing access to protected content. Depending on your existing infrastructure, choose one of two integration patterns.

Approach	Description	Best for
Compute-native	All traffic enters a Fastly Compute service; the SDK handles detection, validation, and origin routing.	Greenfield projects or full Compute migrations.
Service chaining (CDN → Compute)	Your existing VCL service detects the `Authorization: License` header and chains licensed requests to a Compute service for validation.	Existing CDN services using VCL snippets.

Approach 1: Compute-native

The fastlyHandleRequests method manages the full request lifecycle. Use a Fastly SecretStore for the API key.

/// <reference types="@fastly/js-compute" />
import { SupertabConnect } from "@getsupertab/supertab-connect-sdk";
import { SecretStore } from "fastly:secret-store";

const secrets = new SecretStore("supertab_config");
const merchantApiKey = await secrets.get("MERCHANT_API_KEY");

addEventListener("fetch", (event) => {
  event.respondWith(
    SupertabConnect.fastlyHandleRequests(
      event.request,
      merchantApiKey,
      "origin_backend_name",
      {
        merchantSystemUrn: "YOUR_WEBSITE_URN",
        // Bot-event logging: emit one event per request to the "bot_events" endpoint
        // (see the Bot-Event Logging section below)
        analyticsEnabled: true,
        logEndpoint: "bot_events",
      }
    )
  );
});

Install the SDK:

npm install @getsupertab/supertab-connect-sdk

Enforcement modes

import { EnforcementMode } from "@getsupertab/supertab-connect-sdk";

// DISABLED: no enforcement, signaling, or analytics — use during initial integration
SupertabConnect.fastlyHandleRequests(event.request, merchantApiKey, "origin_backend_name", {
  enforcement: EnforcementMode.DISABLED,
});

// SOFT (default): allow all traffic through but log events
SupertabConnect.fastlyHandleRequests(event.request, merchantApiKey, "origin_backend_name", {
  enforcement: EnforcementMode.SOFT,
});

// STRICT: block requests with invalid or missing license tokens
SupertabConnect.fastlyHandleRequests(event.request, merchantApiKey, "origin_backend_name", {
  enforcement: EnforcementMode.STRICT,
});

Bot detection

By default the SDK identifies known crawlers by their user agent. Pass a botDetector function to extend or override this logic.

const isBot = (request) => {
  const ua = request.headers.get("User-Agent") || "";
  return ua.includes("MyCustomBot") || ua.includes("Scraper");
};

SupertabConnect.fastlyHandleRequests(event.request, merchantApiKey, "origin_backend_name", {
  botDetector: isBot,
  enforcement: EnforcementMode.STRICT,
});

Manual verification

For fine-grained control, use verifyAndRecord() directly instead of fastlyHandleRequests.

const result = await supertab.verifyAndRecord({
  token: licenseToken,
  resourceUrl: request.url,
  userAgent: request.headers.get("User-Agent"),
});

if (result.valid) {
  // forward to origin
}

Approach 2: Service Chaining (CDN → Compute)

Use this when you already have a CDN service and only want licensed requests to detour through Compute. The CDN service does the routing via VCL snippets; the Compute service runs the SDK and then forwards to your normal origin.

VCL snippets — `vcl_recv` amd `vcl_pass`

To reroute RSL-licensed requests to the Compute service, add a recv snippet:

if (req.http.Authorization ~ "^License ") {
  set req.backend = F_supertab_compute_validator;
  return (pass);
}

Here supertab-compute-validator indicates the name of the host/backend that you must define in your Fastly CDN service. It should lead to the automatically assigned Compute service’s domain (e.g., your-compute-service.edgecompute.app) which you will create on the next step. Additionally, create a pass snippet:

declare local var.scheme STRING;

if (req.is_ssl) {
  set var.scheme = "https";
} else {
  set var.scheme = "http";
}

set bereq.http.X-Original-Request-Url = var.scheme "://" req.http.host req.url;

This ensures X-Original-Request-Url used to verify the aud claim from license token is included in the request to Compute service. Without it CAP enforcement fails with insufficient_scope error as we are unable to confirm all properties required by RSL spec. Note: keep the rest of your VCL flow intact so non-licensed traffic never leaves the CDN path.

Compute service

/// <reference types="@fastly/js-compute" />
import { SupertabConnect } from "@getsupertab/supertab-connect-sdk";
import { SecretStore } from "fastly:secret-store";

addEventListener("fetch", (event) => {
  event.respondWith((async () => {
    const configDict = new SecretStore("supertab_config");
    const entry = await configDict.get("MERCHANT_API_KEY");
    const merchantApiKey = entry?.plaintext() ?? "";

    return SupertabConnect.fastlyHandleRequests(
      event.request,
      merchantApiKey,
      "origin_backend_name"
    );
  })());
});

The Compute service requires the following configuration to work:

A Secret Store called supertab_config containing MERCHANT_API_KEY and linked to the Compute service
A backend for your real origin, passed as the third argument above (origin_backend_name)
A Supertab backend with stc-backend as the name (see VCL Service - Backend for an example config)
A host called supertab-compute-validator in the CDN service, using the Compute service’s autogenerated *.edgecompute.app domain.

If the SDK rejects the token with an audience or scope error, check that the VCL snippet saving the initial request URL to X-Original-Request-Url header is running before the request reaches Compute.

Bot-Event Logging

When the SDK runs in a Compute service, it can emit one analytics event per request to a Fastly logging endpoint named bot_events. Supertab loads those events into your bot-traffic analytics.

Enable analytics in the SDK

Pass the analytics options to fastlyHandleRequests:

SupertabConnect.fastlyHandleRequests(
  event.request,
  merchantApiKey,
  "origin_backend_name",
  {
    analyticsEnabled: true,
    logEndpoint: "bot_events",
    merchantSystemUrn: "YOUR_WEBSITE_URN",
  }
);

You can find your Merchant System URN on the View Website Details page of the Merchant Portal, in the same place as your API keys. If you prefer not to hardcode it, store it in your Secret Store alongside MERCHANT_API_KEY (e.g. as MERCHANT_SYSTEM_URN) and read it the same way.

Create the S3 logging endpoint

The SDK writes events to a log streaming endpoint that must exist on your Compute service. In the Fastly dashboard, go to Resources → Log streaming → Create endpoint → Amazon S3 and set:

Setting	Value
Name	`bot_events`
Bucket name	`lpeu-prod-connect-bot-events`
Path	`bot-events/`
Domain	`s3.eu-central-1.amazonaws.com` (region `eu-central-1`)
Access key / Secret key	credentials provided by Supertab
Log format	Blank
Compression	none
Period	`900` seconds (15 min)

A few of these are easy to get wrong:

The endpoint name must be exactly bot_events, matching the logEndpoint SDK option — otherwise the logs are silently dropped.
The log format must be Blank. The SDK already writes one JSON object per line; the default (Classic) prepends a syslog header and corrupts every event.
Leave gzip compression off, or the Supertab connector won’t match the *.log objects.
The regional domain s3.eu-central-1.amazonaws.com is required because the bucket is not in us-east-1.

Save the endpoint and activate the service version to start shipping events.

​Publishing RSL License

​VCL Service

​Backend

​Condition

​VCL Snippet

​Compute (Wasm) Service

​CAP Enforcement

​Approach 1: Compute-native

​Enforcement modes

​Bot detection

​Manual verification

​Approach 2: Service Chaining (CDN → Compute)

​VCL snippets — vcl_recv amd vcl_pass

​Compute service

​Bot-Event Logging

​Enable analytics in the SDK

​Create the S3 logging endpoint