OAuth2 Machine-to-Machine Authentication

OAuth2 vs API Keys

AlterLab supports two ways for third-party tools to authenticate: direct API keys and OAuth2. Choose based on your use case.

How It Works

AlterLab implements the standard OAuth2 Authorization Code flow in two steps.

Quick Start

The following examples show the raw API calls. In practice, n8n and Zapier handle steps 1–3 automatically through their credential setup wizard.

Step 1: Get an Authorization Code

The web app calls this endpoint with the user's NextAuth session JWT in the Authorization header. No third-party credentials are needed here.

curl -X POST https://api.alterlab.io/api/v1/oauth/authorize \
  -H "Authorization: Bearer YOUR_NEXTAUTH_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "n8n",
    "redirect_uri": "https://your-n8n.example.com/oauth/callback",
    "state": "random-csrf-token-1234",
    "scope": "scrape",
    "source": "n8n"
  }'

Response:

{
  "code": "abc123xyz789...",
  "state": "random-csrf-token-1234"
}

Step 2: Exchange for an API Key

The third-party backend calls this endpoint — no user session required. Uses client_id and client_secret for authentication.

curl -X POST https://api.alterlab.io/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "abc123xyz789...",
    "client_id": "n8n",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uri": "https://your-n8n.example.com/oauth/callback"
  }'

Response:

{
  "access_token": "sk_live_abc123...",
  "token_type": "bearer",
  "scope": "scrape"
}

Step 3: Use the API Key

The access_token is a standard AlterLab API key. Use it with the X-API-Key header on any scraping endpoint.

curl -X POST https://api.alterlab.io/api/v1/scrape \
  -H "X-API-Key: sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Token Rotation

AlterLab automatically rotates API keys on each OAuth2 token exchange. When a new token is issued for an integration that already has a key, the previous key is immediately revoked.

Scopes

Only one scope is currently supported:

Client Configuration

To register a new OAuth2 client (custom integration), contact [email protected]. You will receive a client_id and client_secret, and your redirect_uri(s) will be added to the allowlist.

Error Reference