webflow-install-auth

Webflow Install & Auth

Overview

Set up the official Webflow JS SDK (webflow-api on npm) and configure authentication using either a workspace/site API token or OAuth 2.0 for Data Client Apps.

Prerequisites

• Node.js 18+
• npm, pnpm, or yarn
• A Webflow account with a workspace
• An API token (workspace or site) from https://developers.webflow.com

Instructions

Step 1: Install the SDK

# npm
npm install webflow-api

# pnpm
pnpm add webflow-api

# yarn
yarn add webflow-api

The package is webflow-api (not @webflow/sdk). Current version: 3.x (Data API v2).

Step 2: Choose Authentication Method

Webflow offers two auth methods:

Method	Use Case	Scope
API Token (workspace)	Server-side scripts, internal tools	All sites in workspace
API Token (site)	Single-site integrations	One site only
OAuth 2.0	Public apps, Webflow Marketplace apps	User-authorized scopes

Step 3: Token-Based Authentication

# Set environment variable (never hardcode tokens)
echo 'WEBFLOW_API_TOKEN=your-token-here' >> .env
echo '.env' >> .gitignore

import { WebflowClient } from "webflow-api";

// Initialize with workspace or site token
const webflow = new WebflowClient({
  accessToken: process.env.WEBFLOW_API_TOKEN!,
});

Step 4: OAuth 2.0 Flow (Data Client Apps)

For apps that need user authorization, implement the OAuth 2.0 authorization code flow:

import express from "express";
import { WebflowClient } from "webflow-api";

const app = express();

const CLIENT_ID = process.env.WEBFLOW_CLIENT_ID!;
const CLIENT_SECRET = process.env.WEBFLOW_CLIENT_SECRET!;
const REDIRECT_URI = "https://yourapp.com/auth/webflow/callback";

// Step 1: Redirect user to Webflow authorization page
// Scopes: sites:read, sites:write, cms:read, cms:write,
//         pages:read, pages:write, forms:read, ecommerce:read,
//         ecommerce:write, custom_code:read, custom_code:write
app.get("/auth/webflow", (req, res) => {
  const scopes = "sites:read cms:read cms:write";
  const authUrl =
    `https://webflow.com/oauth/authorize` +
    `?client_id=${CLIENT_ID}` +
    `&response_type=code` +
    `&redirect_uri=${encodeURIComponent(REDIRECT_URI)}` +
    `&scope=${encodeURIComponent(scopes)}`;
  res.redirect(authUrl);
});

// Step 2: Exchange authorization code for access token
// The authorization code expires in 15 minutes
app.get("/auth/webflow/callback", async (req, res) => {
  const code = req.query.code as string;

  const response = await fetch("https://api.webflow.com/oauth/access_token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
      code,
      grant_type: "authorization_code",
      redirect_uri: REDIRECT_URI,
    }),
  });

  const { access_token } = await response.json();

  // Store access_token securely — it does not expire but can be revoked
  const webflow = new WebflowClient({ accessToken: access_token });
  const { sites } = await webflow.sites.list();

  res.json({ authorized: true, siteCount: sites?.length });
});

Step 5: Verify Connection

import { WebflowClient } from "webflow-api";

const webflow = new WebflowClient({
  accessToken: process.env.WEBFLOW_API_TOKEN!,
});

async function verify() {
  // List all sites accessible with this token
  const { sites } = await webflow.sites.list();

  if (!sites || sites.length === 0) {
    throw new Error("No sites accessible. Check token scopes.");
  }

  for (const site of sites) {
    console.log(`Site: ${site.displayName} (${site.id})`);
    console.log(`  Short name: ${site.shortName}`);
    console.log(`  Last published: ${site.lastPublished}`);
  }
}

verify().catch(console.error);

Webflow API Scopes Reference

Scope	Access
sites:read	List/get sites
sites:write	Publish sites
cms:read	Read collections and items
cms:write	Create/update/delete CMS items
pages:read	List/get pages
pages:write	Update page content
forms:read	Read form submissions
ecommerce:read	Read products, orders, inventory
ecommerce:write	Create/update products, fulfill orders
custom_code:read	Read registered custom code
custom_code:write	Register/apply custom code

Output

• Installed webflow-api package
• Environment variable with API token (.env file, git-ignored)
• Working WebflowClient instance
• Verified connection by listing accessible sites

Error Handling

Error	Cause	Solution
401 Unauthorized	Invalid or revoked token	Generate new token at developers.webflow.com
403 Forbidden	Token missing required scope	Add scopes in app settings or generate new token
429 Too Many Requests	Rate limit exceeded	Wait for Retry-After header (60s reset)
MODULE_NOT_FOUND	Wrong package name	Use webflow-api, not @webflow/sdk
OAuth code expired	Authorization code > 15 min old	Re-initiate OAuth flow promptly

Resources

• Webflow Developer Docs
• SDK npm package
• SDK GitHub repo
• OAuth Reference
• Scopes Reference

Next Steps

After successful auth, proceed to webflow-hello-world for your first API call.