Data API Authentication and Scopes

GET /v2/sites HTTP/1.1
Host: api.webflow.com
Authorization: Bearer REPLACE_WITH_API_TOKEN
Accept: application/json

export WEBFLOW_API_TOKEN="$(cat ~/.config/fernbrook/webflow-token)"

curl --silent --show-error \
  --header "Authorization: Bearer ${WEBFLOW_API_TOKEN}" \
  --header "Accept: application/json" \
  https://api.webflow.com/v2/sites

{
  "name": "fernbrook-content-dashboard",
  "private": true,
  "type": "module",
  "engines": { "node": ">=18" },
  "scripts": { "start": "node server.mjs" },
  "dependencies": {
    "express": "5.3.0",
    "express-session": "1.18.1",
    "webflow-api": "3.3.4"
  }
}

# .env (not committed)
WEBFLOW_CLIENT_ID=REPLACE_WITH_CLIENT_ID
WEBFLOW_CLIENT_SECRET=REPLACE_WITH_CLIENT_SECRET
WEBFLOW_REDIRECT_URI=https://localhost:3000/auth/webflow/callback
SESSION_SECRET=REPLACE_WITH_LONG_RANDOM_STRING

// server.mjs: OAuth authorization-code flow for the Fernbrook Content Dashboard
import crypto from "node:crypto";
import express from "express";
import session from "express-session";
import { WebflowClient } from "webflow-api";

const {
  WEBFLOW_CLIENT_ID: clientId,
  WEBFLOW_CLIENT_SECRET: clientSecret,
  WEBFLOW_REDIRECT_URI: redirectUri,
  SESSION_SECRET: sessionSecret,
} = process.env;

for (const [name, value] of Object.entries({
  WEBFLOW_CLIENT_ID: clientId,
  WEBFLOW_CLIENT_SECRET: clientSecret,
  WEBFLOW_REDIRECT_URI: redirectUri,
  SESSION_SECRET: sessionSecret,
})) {
  if (!value) throw new Error(`Missing environment variable ${name}`);
}

// Ask only for what the dashboard uses: read sites, read and write CMS items.
const SCOPES = ["authorized_user:read", "sites:read", "cms:read", "cms:write"];

const app = express();
app.use(
  session({
    secret: sessionSecret,
    resave: false,
    saveUninitialized: false,
    cookie: { httpOnly: true, secure: true, sameSite: "lax", maxAge: 30 * 60 * 1000 },
  }),
);

// In production this is an encrypted database column, not a Map.
const tokenVault = new Map();

app.get("/auth/webflow", (req, res) => {
  const state = crypto.randomBytes(32).toString("hex");
  req.session.oauthState = state;

  const authorizeUrl = WebflowClient.authorizeURL({
    clientId,
    redirectUri,
    scope: SCOPES,
    state,
  });
  res.redirect(authorizeUrl);
});

app.get("/auth/webflow/callback", async (req, res) => {
  const { code, state, error } = req.query;

  if (error) return res.status(400).send(`Authorization refused: ${error}`);
  if (typeof code !== "string" || typeof state !== "string") {
    return res.status(400).send("Missing code or state");
  }

  const expected = req.session.oauthState;
  delete req.session.oauthState; // one use only
  const a = Buffer.from(state);
  const b = Buffer.from(expected ?? "");
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(400).send("State does not match");
  }

  try {
    const accessToken = await WebflowClient.getAccessToken({
      clientId,
      clientSecret,
      code,
      redirectUri,
    });

    const client = new WebflowClient({ accessToken });

    // What did the user actually grant, and where?
    const introspection = await client.token.introspect();
    const granted = (introspection.authorization?.scope ?? "").split(",");
    const missing = SCOPES.filter((scope) => !granted.includes(scope));
    if (missing.length > 0) {
      return res.status(403).send(`Missing scopes: ${missing.join(", ")}`);
    }

    // Persist per user. Never put the token in the cookie, the URL or the page.
    const userId = introspection.authorization?.authorizedTo?.userIds?.[0];
    tokenVault.set(userId, accessToken);
    req.session.userId = userId;

    res.redirect("/dashboard");
  } catch (err) {
    console.error("Token exchange failed", err?.statusCode ?? "", err?.message);
    res.status(502).send("Could not complete the Webflow connection");
  }
});

app.get("/dashboard", async (req, res) => {
  const accessToken = tokenVault.get(req.session.userId);
  if (!accessToken) return res.redirect("/auth/webflow");

  const client = new WebflowClient({ accessToken });
  try {
    const { sites } = await client.sites.list();
    res.json((sites ?? []).map(({ id, displayName }) => ({ id, displayName })));
  } catch (err) {
    if (err?.statusCode === 401) {
      tokenVault.delete(req.session.userId); // revoked or invalid: reconnect
      return res.redirect("/auth/webflow");
    }
    throw err;
  }
});

app.post("/auth/webflow/disconnect", express.json(), async (req, res) => {
  const accessToken = tokenVault.get(req.session.userId);
  if (accessToken) {
    await fetch("https://webflow.com/oauth/revoke_authorization", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        client_id: clientId,
        client_secret: clientSecret,
        access_token: accessToken,
      }),
    });
    tokenVault.delete(req.session.userId);
  }
  req.session.destroy(() => res.status(204).end());
});

app.listen(3000, () => console.log("Fernbrook Content Dashboard on :3000"));

Flask==3.1.0
webflow==2.0.0
requests==2.32.3

# app.py: OAuth authorization-code flow for the Fernbrook Content Dashboard
import hmac
import os
import secrets

import requests
from flask import Flask, jsonify, redirect, request, session
from webflow.client import Webflow
from webflow.oauth import authorize_url, get_access_token

CLIENT_ID = os.environ["WEBFLOW_CLIENT_ID"]
CLIENT_SECRET = os.environ["WEBFLOW_CLIENT_SECRET"]
REDIRECT_URI = os.environ["WEBFLOW_REDIRECT_URI"]

# Ask only for what the dashboard uses.
SCOPES = ["authorized_user:read", "sites:read", "cms:read", "cms:write"]

app = Flask(__name__)
app.secret_key = os.environ["SESSION_SECRET"]
app.config.update(
    SESSION_COOKIE_HTTPONLY=True,
    SESSION_COOKIE_SECURE=True,
    SESSION_COOKIE_SAMESITE="Lax",
)

# In production this is an encrypted database column, not a dict.
TOKEN_VAULT: dict[str, str] = {}


@app.get("/auth/webflow")
def start_authorization():
    state = secrets.token_hex(32)
    session["oauth_state"] = state
    return redirect(
        authorize_url(
            client_id=CLIENT_ID,
            redirect_uri=REDIRECT_URI,
            scope=SCOPES,
            state=state,
        )
    )


@app.get("/auth/webflow/callback")
def callback():
    if "error" in request.args:
        return f"Authorization refused: {request.args['error']}", 400

    code = request.args.get("code")
    state = request.args.get("state", "")
    expected = session.pop("oauth_state", "")  # one use only
    if not code or not hmac.compare_digest(state, expected):
        return "State does not match", 400

    access_token = get_access_token(
        client_id=CLIENT_ID,
        client_secret=CLIENT_SECRET,
        code=code,
        redirect_uri=REDIRECT_URI,
    )

    client = Webflow(access_token=access_token)
    introspection = client.token.introspect()
    authorization = introspection.authorization
    granted = (authorization.scope or "").split(",")
    missing = [scope for scope in SCOPES if scope not in granted]
    if missing:
        return f"Missing scopes: {', '.join(missing)}", 403

    user_id = authorization.authorized_to.user_ids[0]
    TOKEN_VAULT[user_id] = access_token  # never in the cookie
    session["user_id"] = user_id
    return redirect("/dashboard")


@app.get("/dashboard")
def dashboard():
    access_token = TOKEN_VAULT.get(session.get("user_id", ""))
    if not access_token:
        return redirect("/auth/webflow")

    client = Webflow(access_token=access_token)
    sites = client.sites.list().sites or []
    return jsonify([{"id": s.id, "displayName": s.display_name} for s in sites])


@app.post("/auth/webflow/disconnect")
def disconnect():
    user_id = session.get("user_id", "")
    access_token = TOKEN_VAULT.pop(user_id, None)
    if access_token:
        requests.post(
            "https://webflow.com/oauth/revoke_authorization",
            json={
                "client_id": CLIENT_ID,
                "client_secret": CLIENT_SECRET,
                "access_token": access_token,
            },
            timeout=10,
        )
    session.clear()
    return "", 204

curl --silent --show-error --request POST \
  --url https://webflow.com/oauth/revoke_authorization \
  --header "Content-Type: application/json" \
  --data "{
    \"client_id\": \"${WEBFLOW_CLIENT_ID}\",
    \"client_secret\": \"${WEBFLOW_CLIENT_SECRET}\",
    \"access_token\": \"${ACCESS_TOKEN_TO_REVOKE}\"
  }"

{ "did_revoke": true }

import { WebflowClient } from "webflow-api";

function requireEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    console.error(`Missing ${name}`);
    process.exit(2);
  }
  return value;
}

export const client = new WebflowClient({
  accessToken: requireEnv("WEBFLOW_API_TOKEN"),
});

name: fernbrook-sync
on:
  schedule:
    - cron: "0 3 * * *"
  workflow_dispatch:

permissions:
  contents: read

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: node scripts/check-token-scopes.mjs
        env:
          WEBFLOW_API_TOKEN: ${{ secrets.WEBFLOW_API_TOKEN }}
      - run: node scripts/sync.mjs
        env:
          WEBFLOW_API_TOKEN: ${{ secrets.WEBFLOW_API_TOKEN }}
          WEBFLOW_SITE_ID: ${{ vars.WEBFLOW_SITE_ID }}