SmartURLs

Run a SmartURLs redirect domain with the official Go or PHP client, including redirect handling, JavaScript verification, reverse proxy setup, and security requirements.

SmartURLs lets you run short, trackable redirect URLs that can apply STOPBOT visitor analysis before sending a visitor to the final destination.

Use this guide when you want to host your own SmartURLs redirect domain, for example:

https://links.example.com/swWV8j

The public visitor URL uses your own domain and the SmartURLs keyname. Your server-side SmartURLs client then sends the visitor context to STOPBOT V2.

Recommended Integration

Use one of the official SmartURLs V2 clients:

Client	Recommended for	Repository
Go client	Production servers, VPS, reverse proxy deployments, high traffic redirect domains	Stopbot-SmartURLs-V2-Go
PHP client	Shared hosting, Apache/PHP hosting, existing PHP environments	Stopbot-SmartURLs-V2-PHP

The Go client is recommended for most production deployments.

Endpoint Used By The Clients

Both clients call:

GET https://api.stopbot.net/services/shorterlink

You normally do not need to call this endpoint directly from frontend code. Keep the STOPBOT API key on your server.

How SmartURLs Works

1. Create a SmartURLs keyname in the STOPBOT panel.

2. Deploy the Go or PHP SmartURLs client on your redirect domain.

3. A visitor opens https://your-domain.example/{keyname}.

4. The client sends the visitor IP, user agent, URL, and keyname to STOPBOT V2.

5. STOPBOT returns a redirect decision.

6. The client redirects the visitor, shows a local error page, or runs JavaScript browser verification first.

Create A SmartURLs Keyname

1. Sign in to panel.stopbot.net.

2. Open the SmartURLs or Shortlink section.

3. Create a new SmartURLs key, or open an existing one.

4. Configure the destination URL and protection rules.

5. Copy the SmartURLs keyname.

If the panel shows:

https://panel.stopbot.net/shortlink-swWV8j

the keyname is:

swWV8j

Your public visitor URL becomes:

https://your-domain.example/swWV8j

Allowed keyname characters:

A-Z a-z 0-9 . _ -

The maximum length is 64 characters.

Go Client Setup

Clone the Go client:

git clone https://github.com/stopbot-net/Stopbot-SmartURLs-V2-Go.git
cd Stopbot-SmartURLs-V2-Go

Copy the environment example:

cp .env.example .env

Configure .env:

STOPBOT_API_KEY=your_api_key
SMARTURLS_ADDR=127.0.0.1:8080
STOPBOT_API_ENDPOINT=https://api.stopbot.net/services/shorterlink
SMARTURLS_SIGNING_KEY=change_this_to_a_long_random_secret_value
SMARTURLS_TRUST_PROXY_HEADERS=true

SMARTURLS_SIGNING_KEY is a private local secret used to protect browser verification tokens. It is not your STOPBOT API key and does not need to be configured in the STOPBOT panel.

Recommended signing key characters:

A-Z a-z 0-9 _ - . @ # %

Use at least 32 characters. Avoid spaces and quotes.

Build and run:

go test ./...
go build -o smarturls .
./smarturls

On Windows:

go test ./...
go build -o smarturls.exe .
.\smarturls.exe

The Go binary embeds the local message template. Rebuild the binary after editing template/message.html.

Go Client With Nginx

Nginx is the recommended reverse proxy for the Go client.

Example Nginx server block:

server {
    listen 80;
    server_name your-domain.example;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Use:

SMARTURLS_TRUST_PROXY_HEADERS=true

only when the Go application is always behind a trusted reverse proxy and cannot be accessed directly from the internet.

PHP Client Setup

Clone or download the PHP client:

git clone https://github.com/stopbot-net/Stopbot-SmartURLs-V2-PHP.git

Upload the PHP client files to your SmartURLs domain.

Set the API key through an environment variable:

STOPBOT_API_KEY=your_api_key

Or create config.local.php next to config.php:

<?php
$StopbotApiKey = 'your_api_key';
$SmartUrlsSigningKey = 'change_this_random_secret';
$SmartUrlsTrustProxyHeaders = true;

Do not commit config.local.php.

Apache

The PHP client includes .htaccess rules. A request like:

https://your-domain.example/swWV8j

is routed internally to:

index.php?q=swWV8j

Nginx

Nginx does not read .htaccess, so add a rewrite rule:

server {
    listen 80;
    server_name your-domain.example;

    root /var/www/smarturls;
    index index.php;

    location / {
        try_files $uri $uri/ @smarturls;
    }

    location @smarturls {
        rewrite ^/(.*)$ /index.php?q=$1&$args last;
    }

    location ~ \.php$ {
        try_files $fastcgi_script_name =404;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    }
}

Adjust root and fastcgi_pass for your server.

Redirect Decision Handling

The SmartURLs clients handle common STOPBOT redirect decisions:

API value	Client behavior
valid redirectTo URL	Redirects the visitor
STOPBOTNET 403	Shows the local 403 message page
STOPBOTNET 404	Shows the local 404 message page
empty redirectTo	Shows the local 404 message page
SERVER NOT RESPOND	Shows the local 503 message page
invalid redirect value	Shows the local 502 message page

The local message page is included in the client template and can be customized.

The final redirect action must come from blockAccess and redirectTo, not from isBot. isBot is only a visitor classification signal. A SmartURLs visitor can be human/non-bot and still receive the blocked redirect when your keyname configuration blocks that request.

Example country restriction response:

{
  "isBot": 0,
  "blockAccess": 1,
  "detectActivity": "BLOCK BY COUNTRY."
}

JavaScript Verification Flow

When JavaScript verification is enabled for a SmartURLs keyname, STOPBOT V2 returns:

{
  "redirectTo": "https://example.com",
  "jsResponse": 1,
  "uniqueCode": "abc123def456"
}

The current Go and PHP clients do not expose the API key to the browser. They create a local signed token and render a browser check page.

The browser calls the local client:

/rsc/rjs.json?token=...

The server verifies the local token, then calls STOPBOT V2 with:

apikey={API_KEY}
ip={VISITOR_IP}
keyname={KEYNAME}
js=1
code={uniqueCode}

Example API verification request:

https://api.stopbot.net/services/shorterlink?apikey={API_KEY}&ip=1.1.1.1&keyname={KEYNAME}&js=1&code={UNIQUE_CODE}

Successful verification response:

{
  "AddVisitorStatus": 1,
  "status": "success"
}

After verification succeeds, the client redirects the visitor to the destination URL.

Important Security Notes

• Keep the STOPBOT API key on the server.

• Do not place the API key in browser JavaScript.

• Do not commit .env or config.local.php.

• Use a long random signing key for browser verification tokens.

• Enable proxy header trust only behind a trusted reverse proxy.

• Make sure the API key belongs to the same STOPBOT account that owns the SmartURLs keyname.

Test Checklist

• Open https://your-domain.example/{keyname}.

• Confirm the visitor reaches the expected destination URL.

• Confirm blocked traffic shows the local message page or follows the configured redirect behavior.

• If JavaScript verification is enabled, confirm /rsc/rjs.json?token=... returns a successful verification response.

• Check SmartURLs statistics in the STOPBOT panel.

• Confirm the API key is not visible in browser page source or network calls.

V1 Difference

Legacy SmartURLs V1 used keyname-based JavaScript tracking.

Current SmartURLs V2 uses a uniqueCode verification flow:

js=1&keyname={KEYNAME}&code={uniqueCode}

Use the current Go or PHP V2 client for new integrations.