Authentication

API authentication and authorization for PinchTab

Overview

PinchTab supports optional Bearer token authentication. When enabled, all API requests must include a valid authentication token.

Authentication is disabled by default. Enable it by setting the BRIDGE_TOKEN environment variable when starting the server.

Enabling Authentication

Set the BRIDGE_TOKEN environment variable:

export BRIDGE_TOKEN="your_secret_token_here"
pinchtab

Or inline:

BRIDGE_TOKEN="your_secret_token_here" pinchtab

Use a strong, randomly generated token in production environments.

Making Authenticated Requests

Include the token in the Authorization header with the Bearer prefix:

cURL

curl -H "Authorization: Bearer your_secret_token_here" \
  http://localhost:9867/instances

Authentication Errors

Missing Token (401 Unauthorized)

Request:

curl http://localhost:9867/instances

Response:

{
  "error": "authentication required",
  "statusCode": 401
}

Invalid Token (401 Unauthorized)

Request:

curl -H "Authorization: Bearer wrong_token" \
  http://localhost:9867/instances

Response:

{
  "error": "invalid authentication token",
  "statusCode": 401
}

Security Best Practices

Token Generation

Generate a strong random token:

# Linux/macOS
openssl rand -hex 32

# Or use a password manager to generate a strong token

Environment Variables

Store tokens in environment variables, not in code:

# .env file (do not commit to version control)
BRIDGE_TOKEN=abc123def456...

# Load in your shell
export $(cat .env | xargs)
pinchtab

HTTPS in Production

Always use HTTPS in production to prevent token interception. Place PinchTab behind a reverse proxy (nginx, Caddy) with TLS.

Example nginx configuration:

server {
    listen 443 ssl http2;
    server_name api.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:9867;
        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;
    }
}

Token Rotation

Rotate tokens periodically:

1. Generate a new token
2. Update the BRIDGE_TOKEN environment variable
3. Restart PinchTab
4. Update all clients with the new token

Access Control

For multi-user scenarios:

• Single Token: All users share one token (simple but less secure)
• Reverse Proxy Auth: Use nginx/Caddy for per-user authentication
• API Gateway: Use an API gateway (Kong, Tyk) for advanced auth

Tab Locking (Multi-Agent Coordination)

For multi-agent scenarios, use tab locking to prevent concurrent access:

Lock a Tab

owner · string · required

Unique identifier for the agent/user locking the tab

ttl · integer

Time-to-live in seconds (default: 60)

curl -X POST http://localhost:9867/tabs/tab_abc12345/lock \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "owner": "agent-1",
    "ttl": 120
  }'

Response:

{
  "locked": true,
  "owner": "agent-1",
  "expiresAt": "2026-03-03T12:34:56Z"
}

Unlock a Tab

curl -X POST http://localhost:9867/tabs/tab_abc12345/unlock \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "owner": "agent-1"
  }'

Response:

{
  "unlocked": true
}

Owner Header

Include the owner in the X-Owner header for automatic enforcement:

curl -X POST http://localhost:9867/tabs/tab_abc12345/action \
  -H "Authorization: Bearer your_token" \
  -H "X-Owner: agent-1" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "click",
    "ref": "e5"
  }'

If the tab is locked by a different owner:

{
  "error": "tab tab_abc12345 is locked by agent-2",
  "code": "tab_locked",
  "statusCode": 423
}

Example: Multi-Agent Setup

import requests
import time

BASE = "http://localhost:9867"
TOKEN = "your_secret_token"
AGENT_ID = "agent-1"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "X-Owner": AGENT_ID,
    "Content-Type": "application/json"
}

# Start instance
inst = requests.post(f"{BASE}/instances/start", 
    headers=headers, json={"mode": "headed"}).json()

# Open tab
tab = requests.post(f"{BASE}/instances/{inst['id']}/tabs/open",
    headers=headers, json={"url": "https://example.com"}).json()

tab_id = tab["tabId"]

# Lock tab
requests.post(f"{BASE}/tabs/{tab_id}/lock",
    headers=headers, json={"owner": AGENT_ID, "ttl": 300})

try:
    # Do work (tab is locked to this agent)
    requests.post(f"{BASE}/tabs/{tab_id}/action",
        headers=headers, json={"kind": "click", "ref": "e5"})
    
    time.sleep(2)
    
    # Get snapshot
    snapshot = requests.get(f"{BASE}/tabs/{tab_id}/snapshot?filter=interactive",
        headers=headers).json()
    
finally:
    # Always unlock when done
    requests.post(f"{BASE}/tabs/{tab_id}/unlock",
        headers=headers, json={"owner": AGENT_ID})

No Authentication Mode

When BRIDGE_TOKEN is not set, all endpoints are accessible without authentication:

# No token required
curl http://localhost:9867/instances
curl http://localhost:9867/tabs

Use no-auth mode only for local development or trusted network environments.

Summary

Enable Auth

Set BRIDGE_TOKEN environment variable

Use Bearer Tokens

Include Authorization: Bearer <token> header

Tab Locking

Use X-Owner header for multi-agent safety

HTTPS in Production

Always use TLS with reverse proxy

Next Steps

• Instances API - Create and manage browser instances
• Tabs API - List and control tabs
• Actions API - Automate browser interactions