Webflow Custom Code APIがBearerトークンで叩けない理由：invalid_auth_versionの正体

Webflowサイトに外部からカスタムコード（トラッキングタグやスクリプト）を注入しようとして、APIを叩いたらこんなエラーが返ってきました。

{
  "message": "Your token is not authorized to access this version of the API",
  "code": "invalid_auth_version"
}

エラーコードは invalid_auth_version（無効な認証バージョン）。「APIのバージョン指定が間違っているのか」とヘッダーをいじっても直らない。

このエラーの正体は、APIバージョンの問題ではなく認証方式の制約です。Webflow Custom Code APIの落とし穴と、数ページの軽量実装での現実的な回避策をまとめます。

用語補足：

• OAuth＝アプリに代理アクセスを許可する認証方式。ユーザーが「このアプリにこの操作を許可する」と承認する。
• custom code＝Webflowのページに自分で書き足すHTML/CSS/JS。トラッキングタグや外部スクリプトの埋め込みに使う。
• Bearer Token＝サイトごとに発行する固定の認証トークン。リクエストヘッダーに付けてAPIを叩く。

結論：Custom Code APIはOAuth App経由でしか叩けない

要点はこの4つです。

• Webflow Data APIの Custom Code系エンドポイントは、OAuth App経由でしか叩けない
• Site-level Bearer Token は、Custom Code権限を全付与しても invalid_auth_version で拒否される
• invalid_auth_version は「APIバージョン」ではなく認証方式の不一致を意味する
• 数ページの軽量実装なら、Embed要素方式に切り替えるのが現実解

トークンに権限を足せば叩けると思って権限を全部付けても解決しません。Bearerトークン自体がCustom Code APIの対象外だからです。

Site TokenとOAuthの境界

WebflowのData APIには、Site-level Bearer Token（サイトごとに発行する固定トークン）で叩けるものと、OAuth App経由でないと叩けないものがあります。境界は読み取り系か書き込み系かではなく、エンドポイントの種類で決まる。

Site Tokenで叩ける（読み取り系中心）

Site Tokenで叩けない（Custom Code系）

CMSのデータ取得やページ構造の読み取りはSite Tokenで済みますが、カスタムコードの注入はOAuth App必須です。CMSデータの扱い方はWebflow CMSの運用ガイドでまとめています。

エラーコードの誤解を解く

invalid_auth_version というコード名は、強烈にミスリードです。

"message": "Your token is not authorized to access this version of the API"

このメッセージを見ると、「API version 2.0.0 の指定が間違っているのか」「accept-version ヘッダーを変えればいいのか」と考えてしまう。

実態は「このトークン（Bearer）では、このエンドポイントにアクセスできない」という認証方式の問題でした。APIバージョンをいくらいじっても直りません。Bearer Token から OAuth App へ、認証方式そのものを変える必要があります。

現実的な回避策：Embed要素方式

「OAuth Appを登録すれば叩ける」のは事実です。ただしOAuth App登録 → Workspaceインストール → OAuthフロー構築 → トークン保存、という工程は工数が大きい。数ページにスクリプトを入れたいだけなら割に合いません。

軽量実装ならEmbed要素方式が現実解になる。

• Webflow Designerで「Embed」要素をページに配置
• そこにHTML/CSS/JSを直接貼り付ける
• Symbol化すれば、複数ページへの展開・保守も楽になる

Webflow Designer → Embed要素を配置 → コードをコピペ → Publish

判定フロー

数ページならEmbed要素で5分あれば配置できます。構造把握が必要なら、Site Tokenで取得できる GET /v2/pages/{id}/dom（DOM読み取り）を併用すればいい。

アンチパターン3つ

アンチパターン1: トークンに権限を足せば叩けると思う

WebflowダッシュボードでトークンにCustom Code権限を付与しても解決しません。Bearerトークン自体が対象外なので、認証方式を変える必要があります。

アンチパターン2: invalid_auth_versionをAPIバージョン問題と誤解する

エラーコード名に惑わされて accept-version ヘッダーをいじり続けると時間を溶かす。認証方式（Bearer vs OAuth）の問題だと理解するのが先です。

アンチパターン3: 数ページの実装でOAuth Appを構築する

軽量実装にOAuthフローを組むのは過剰です。Embed要素方式で十分。OAuthは大規模・継続自動化のときだけで足ります。

まとめ：エラーコードに惑わされず、認証方式を見る

Webflow Custom Code APIの落とし穴は次の4点に整理できます。

invalid_auth_version というエラーコードに引っ張られて「バージョン指定」を疑うと、何時間も溶かします。実態は認証方式の制約だと知っていれば、すぐにEmbed方式へ切り替えられる。

Webflow運用・自動化でお困りなら

Webflowで「やりたいことに対して、どこまでAPIで自動化できて、どこから手動なのか」がわからず手が止まる。社内にWebflow APIの仕様まで踏み込める人がいない。そんな状況なら、見極めの部分だけでも外に投げる手があります。

f2t.jpでは、Webflowサイトの運用から外部システム連携・トラッキング実装まで一貫してお手伝いしています。お問い合わせフォームからお気軽にどうぞ。