認証・環境設定に関する用語

A.2 認証・環境設定に関する用語

Square APIを使ってECサイトを作るとき、最初に立ちはだかるのが「認証」と「環境設定」です。

決済リンクを作成する前に、Squareへ次のことを伝えなければなりません。

誰が作ったアプリなのか
どのSquareアカウントを操作するのか
どの店舗の売上として扱うのか
テストなのか、本番なのか
どのAPI仕様を使うのか

ここでは、小さな食品店が新しいオンラインショップを開く場面を想像してみましょう。

店舗はNext.jsで商品ページを作りました。

商品写真も価格もカートも完成しています。

しかし、購入ボタンを押しても、まだSquareへ決済を依頼することはできません。

Squareから見ると、そのECサイトが誰なのか分からないからです。

Next.js：
10,000円の決済を作ってください

Square：
あなたは誰ですか？
どの店舗の決済ですか？
テストですか、本番ですか？

そこで必要になるのが、次の認証情報です。

Application ID
Access Token
Location ID
Environment
API Version

攻略本風に言えば、A.2は**「Squareの城へ入るための身分証・鍵・行き先を準備するステージ」**です。

---

A.2.1 Access Token

Access Tokenとは

Access Tokenは、アプリケーションがSquare APIへ安全にアクセスするための認証情報です。

Square APIを呼び出すとき、アプリケーションはAccess Tokenを使って、次の2点を証明します。

このリクエストは認証されたアプリから送られている

このSquareアカウントの情報へアクセスする権限がある

Square公式では、Access Tokenを、Squareアカウント内の顧客、注文、決済などのリソースへ安全にアクセスするための認証情報として説明しています。

現実の店舗に例えると、Access Tokenは管理室へ入るための鍵です。

Application ID：
店舗やアプリの名前札

Access Token：
管理室へ入る鍵

名前札だけを持っていても、管理室には入れません。

Square APIでも、Application IDを知らせるだけでは、注文や決済情報を操作できません。

Access Tokenが必要です。

Access Tokenを使う流れ

Next.jsからSquare APIへリクエストを送るときは、HTTPのAuthorizationヘッダーにAccess Tokenを含めます。

Authorization: Bearer {ACCESS_TOKEN}

Squareは、このTokenを確認してAPI処理を許可します。

Next.js
  ↓
Access Token付きでAPIを呼び出す
  ↓
SquareがTokenを確認
  ↓
認証成功
  ↓
注文・決済処理を実行

Access Tokenがない場合や、無効なTokenを使った場合は、認証エラーになります。

Access Tokenは公開しない

Access Tokenは秘密情報です。

第三者に知られると、そのTokenが持つ権限の範囲で、Squareアカウントの注文、顧客、決済などへアクセスされる危険があります。

そのため、次の場所には絶対に書きません。

・GitHubへ公開するコード
・ブラウザで動くJavaScript
・HTML
・画面に表示するエラー
・開発ログ
・チャットやメール

次のようなコードは危険です。

// 悪い例：コード内にTokenを直接書いている
const accessToken = 'EAAAxxxxxxxxxxxxxxxx';

さらに、Client ComponentでAccess Tokenを使うのも危険です。

'use client';

// 危険：ブラウザへ秘密情報が渡る可能性がある
const accessToken = process.env.NEXT_PUBLIC_SQUARE_ACCESS_TOKEN;

NEXT_PUBLIC_が付いた環境変数は、Next.jsのビルド時にブラウザ向けJavaScriptへ含まれるため、Access Tokenには使用できません。Next.jsでは、NEXT_PUBLIC_を付けていない環境変数は、基本的にサーバー側でのみ利用できます。

Next.jsでの管理方法

Access Tokenは、.env.localやVercelのEnvironment Variablesに保存します。

SQUARE_ACCESS_TOKEN=xxxxxxxxxxxxxxxx

サーバー側では、次のように取得します。

/**
 * 役割: Square Access Tokenを環境変数から取得する
 * 入力: なし
 * 出力: Access Token
 */
export function getSquareAccessToken(): string {
  const accessToken = process.env.SQUARE_ACCESS_TOKEN;

  if (!accessToken) {
    throw new Error('SQUARE_ACCESS_TOKEN is not configured.');
  }

  return accessToken;
}

この関数は、Route Handler、Server Action、Server Componentなど、サーバー側だけで使用します。

購入者のブラウザ
  ↓
Next.jsのサーバー
  ↓
Access Tokenを読み込む
  ↓
Square API

Access Tokenには種類がある

SquareのAccess Tokenには、大きく次の2種類があります。

Personal Access Token：
自分のSquareアカウントへ接続する

OAuth Access Token：
他のSquare事業者から許可を受けて接続する

Square公式では、自分のSquareアカウントだけを利用する専用システムにはPersonal Access Token、複数のSquare事業者へサービスを提供するアプリにはOAuth Access Tokenを使う方針が示されています。

本書で作る1店舗専用のECサイトでは、基本的にPersonal Access Tokenを使います。

---

A.2.2 Application ID

Application IDとは

Application IDは、Squareに登録されたアプリケーションを識別するためのIDです。

Application ID
=
どのアプリケーションなのかを表す名前札

たとえば、Square Developer Consoleに次のアプリを登録したとします。

アプリ名：
金七商店オンラインストア

Application ID：
sq0idp-xxxxxxxxxxxxxxxx

SquareはApplication IDを使って、どのアプリケーションに関する処理なのかを識別します。

Access Tokenとの違い

Application IDとAccess Tokenは似ていますが、役割が異なります。

項目	役割	公開可否
Application ID	アプリケーションを識別する	利用場面によっては公開可能
Access Token	Square APIへのアクセスを認証・許可する	公開不可
Application Secret	OAuthなどでアプリの正当性を証明する	公開不可

Application IDは、OAuthではclient_idとして使われる公開情報です。一方、Application Secretはパスワードに相当する秘密情報であり、公開してはいけません。

イメージすると、次のようになります。

Application ID：
会社名が書かれた社員証

Access Token：
入室権限を持つカードキー

Application Secret：
会社だけが知っている暗証情報

Application IDを使う場面

Application IDは、主に次のような場面で使われます。

・OAuth認証
・Web Payments SDK
・アプリケーションの識別
・SandboxとProductionの切り替え

ただし、SquareのREST APIをサーバーから呼び出す通常の処理では、Access Tokenを使って認証するため、すべてのAPIリクエストにApplication IDを入れるわけではありません。

SandboxとProductionで異なる

Application IDも、SandboxとProductionで異なる場合があります。

Sandbox Application ID
Production Application ID

OAuthやSDKを設定するときは、使用する環境とApplication IDを一致させます。

Sandbox URL
  ＋
Sandbox Application ID

Production URL
  ＋
Production Application ID

環境が混ざると、認証エラーの原因になります。

---

A.2.3 Location ID

Location IDとは

Location IDは、Square上の店舗や販売拠点を識別するIDです。

Squareでは、1つの事業者アカウント内に複数のLocationを持つことができます。

本店
名古屋店
東京店
ECサイト
催事用店舗

それぞれに異なるLocation IDが割り当てられます。

Squareでは、新しく作成されたLocationごとに固有のLocation IDが発行されます。また、決済、返金、在庫管理など、一部のAPI処理は特定のLocationに関連付けられます。

なぜLocation IDが必要なのか

ECサイトから決済を作るとき、Squareは次のことを知る必要があります。

この売上は、どの店舗の売上なのか

たとえば、同じ会社が次の売り場を運営しているとします。

本店
ECサイト
百貨店催事

Locationを分けることで、売上、在庫、レポートなどを販売拠点ごとに整理できます。

本店の売上
ECの売上
催事の売上

Square公式でも、複数のLocationを使うことで、売上活動、在庫、レシート、レポート、取扱商品などを拠点ごとに分けられると説明されています。

1店舗だけの場合

1店舗だけで運用する場合は、Squareアカウント作成時に用意されたメインLocationを利用できます。

SQUARE_LOCATION_ID=XXXXXXXXXXXX

本書のような小規模ECでは、まず既存のメインLocationを使い、実店舗とECの売上を分けたくなった段階で、EC専用Locationを検討しても構いません。

EC専用Locationを作る場合

実店舗とECを明確に分けたい場合は、次のような構成を考えられます。

Location A：
実店舗

Location B：
オンラインストア

これにより、Square側でもEC売上を区別しやすくなります。

ただし、Locationを増やすと、商品、在庫、レポート、運用ルールも増えます。

小規模ECでは、必要になるまでは1つのLocationで始める方が簡単です。

SandboxのLocationは本番と別

Sandboxには、テスト専用のLocationが用意されます。

このLocationはProductionの店舗とは関係ありません。Sandbox Location IDは、Developer ConsoleのSandbox環境にあるLocations画面、またはSandbox Access Tokenを使ったLocations APIから確認できます。

Sandbox Location ID
  ≠
Production Location ID

次の組み合わせは使えません。

Sandbox Access Token
  ＋
Production Location ID

必ず同じ環境の認証情報を組み合わせます。

---

A.2.4 Environment（Sandbox / Production）

Environmentとは

Environmentは、Square APIをどの世界で実行するかを表します。

Squareには、次の2つの環境があります。

Sandbox：
練習用の世界

Production：
実際に販売する世界

Sandbox環境

Sandboxは、実際の購入者や本番データへ影響を与えずにSquare APIをテストするための独立した環境です。

Sandboxでできること

・APIリクエストのテスト
・注文作成
・テスト決済
・顧客登録
・在庫更新
・Webhook確認
・OAuth確認

Sandboxではテスト用のカード情報や決済値を使い、実際のお金を動かさずに決済フローを確認できます。

SandboxのAPI URLは次の通りです。

https://connect.squareupsandbox.com/v2

Production環境

Productionは、実際の購入者、注文、商品、決済を扱う本番環境です。

Productionで決済
  ↓
実際のカード処理
  ↓
Square上に売上記録
  ↓
実際の店舗運用へ

ProductionのAPI URLは次の通りです。

https://connect.squareup.com/v2

SquareのREST APIでは、SandboxとProductionでベースURLが異なり、URLに対応したAccess Tokenを使用する必要があります。

SandboxとProductionは別世界

Sandboxで作成したデータは、Productionには移動しません。

Sandboxで作成した商品
Sandboxで作成した顧客
Sandboxで作成した注文

これらはProductionには存在しない

同様に、認証情報も別です。

Sandbox Access Token
Production Access Token

Sandbox Location ID
Production Location ID

Sandbox Application ID
Production Application ID

Square公式でも、SandboxはProductionから分離されたテスト環境であり、Sandbox用のAccess Tokenを使う必要があると説明されています。

Next.jsでの環境設定

ローカル開発では、Sandbox情報を設定します。

SQUARE_ENVIRONMENT=sandbox
SQUARE_ACCESS_TOKEN=Sandbox用Access Token
SQUARE_LOCATION_ID=Sandbox用Location ID

本番環境では、Production情報を設定します。

SQUARE_ENVIRONMENT=production
SQUARE_ACCESS_TOKEN=Production用Access Token
SQUARE_LOCATION_ID=Production用Location ID

環境に応じてSquare Clientを切り替えます。

type SquareEnvironment = 'sandbox' | 'production';

/**
 * 役割: Square APIの接続先を環境に応じて返す
 * 入力: Square環境
 * 出力: Square APIのベースURL
 */
export function getSquareBaseUrl(
  environment: SquareEnvironment
): string {
  if (environment === 'production') {
    return 'https://connect.squareup.com/v2';
  }

  return 'https://connect.squareupsandbox.com/v2';
}

本番切り替えで変更する項目

SandboxからProductionへ移行するときは、次をまとめて確認します。

□ SQUARE_ENVIRONMENT
□ Access Token
□ Application ID
□ Location ID
□ APIのベースURL
□ Webhook URL
□ Webhook Signature Key
□ OAuth Redirect URL

1つだけProductionに変え、残りがSandboxのままだと正常に動きません。

---

A.2.5 OAuth

OAuthとは

OAuthは、別のSquare事業者から許可を受け、その事業者のSquareアカウントへアクセスする仕組みです。

たとえば、自分の会社が複数の店舗へECシステムを提供するとします。

店舗AのSquare
店舗BのSquare
店舗CのSquare

自社システムが各店舗のAccess Tokenを直接受け取って管理するのは危険です。

そこで、各店舗にSquareの認可画面を開いてもらい、必要な権限だけを許可してもらいます。

店舗が連携ボタンを押す
  ↓
Squareの認可画面
  ↓
店舗が権限を確認
  ↓
連携を許可
  ↓
自社サービスがOAuth Access Tokenを取得

Square OAuth APIは、Square事業者から特定の権限を受け取り、その事業者に代わってSquare APIを呼び出すための仕組みです。

OAuthで取得するもの

OAuthのCode Flowでは、主に次の情報を扱います。

Authorization Code：
許可後に一度だけ使う交換用コード

Access Token：
Square APIを呼ぶためのToken

Refresh Token：
新しいAccess Tokenを取得するためのToken

SquareのOAuth Access Tokenは有効期限があり、Code FlowではRefresh Tokenを使って更新します。

自社専用ECでは必要か

自社のSquareアカウントだけへ接続するECなら、通常はOAuthを使わず、Personal Access Tokenを使う方がシンプルです。

自社のSquare
  ＋
自社のECだけ

→ Personal Access Token

複数のSquare事業者へサービスを提供する場合は、OAuthを使います。

複数店舗が登録するECサービス
予約管理SaaS
POS連携サービス
Square向け外部アプリ

→ OAuth Access Token

Square公式でも、複数の事業者へ提供するマルチテナント型アプリでは、OAuth Access Tokenの使用が案内されています。

権限は必要最小限にする

OAuthでは、アプリが必要とする権限をscopeとして指定します。

ORDERS_READ
ORDERS_WRITE
CUSTOMERS_READ
PAYMENTS_READ

使わない権限まで要求しないことが基本です。

Square公式でも、アプリに必要な権限だけを要求する最小権限の考え方が推奨されています。

---

A.2.6 Personal Access Token

Personal Access Tokenとは

Personal Access Tokenは、自分が所有するSquareアカウントのリソースへアクセスするためのTokenです。

自分のSquareアカウント
  ↓
自分で作ったNext.js EC

このような専用システムに向いています。

Square公式では、自分のSquareアカウントだけへアクセスするカスタム連携に、Personal Access Tokenを使用できると説明されています。

OAuth Access Tokenとの違い

項目	Personal Access Token	OAuth Access Token
主な用途	自社専用システム	複数事業者向けサービス
対象	自分のSquareアカウント	許可したSquare事業者
権限	自分のアカウントへ広くアクセス	許可されたスコープ
取得方法	Developer Console	OAuth認可フロー
実装難易度	比較的低い	高い

本書で作る小規模ECでは、基本的に次の構成です。

Next.js
  ↓
Personal Access Token
  ↓
自社のSquareアカウント

管理上の注意

Personal Access Tokenも、通常のパスワード以上に重要な秘密情報です。

□ コードへ直接書かない
□ GitHubへ登録しない
□ NEXT_PUBLIC_を付けない
□ ログへ出力しない
□ 必要な担当者以外へ共有しない
□ 漏洩の疑いがあれば再発行する

Sandbox用とProduction用は別々に管理します。

# ローカル開発
SQUARE_ACCESS_TOKEN=Sandbox用Token

Vercel Production：
Production用Token

---

A.2.7 Bearer Token

Bearer Tokenとは

Bearer Tokenは、Access Tokenそのものの種類ではなく、HTTP通信でTokenを送る認証方式です。

Square APIでは、Access TokenをAuthorizationヘッダーに次の形式で入れます。

Authorization: Bearer {ACCESS_TOKEN}

Square公式のREST API仕様でも、SquareのAccess TokenはBearer TokenとしてAuthorizationヘッダーへ設定すると説明されています。

Bearerは、簡単に言えば次の意味です。

このTokenを持っている人を、
認証済みの利用者として扱う

そのため、Tokenを持っている人が誰かよりも、「有効なTokenを持っているか」が重要です。

APIリクエストの例

curl https://connect.squareupsandbox.com/v2/locations \
  -H "Authorization: Bearer ${SQUARE_ACCESS_TOKEN}" \
  -H "Content-Type: application/json"

このリクエストでは、次の情報を送っています。

接続先：
Square Sandbox

認証方式：
Bearer

認証情報：
Access Token

データ形式：
JSON

HTTPSが必要な理由

Bearer Tokenは、盗まれると第三者に利用される可能性があります。

そのため、通信を暗号化するHTTPSが必要です。

HTTP：
通信内容を安全に保護できない

HTTPS：
Tokenを含む通信を暗号化する

SquareのProduction API URLはHTTPSです。

Next.js側の本番URLやOAuth Redirect URL、Webhook URLなども、原則としてHTTPSで運用します。OAuthのProduction Redirect URLにはHTTPSが必要です。

Bearer Tokenをログに出さない

次のようなログは避けます。

// 悪い例
console.log({
  accessToken: process.env.SQUARE_ACCESS_TOKEN,
});

エラー調査では、Tokenそのものではなく、次の情報を残します。

・API名
・HTTPステータス
・Squareのエラーコード
・自社注文ID
・処理日時
・使用環境

---

A.2.8 API Version

API Versionとは

API Versionは、Square APIのどの時点の仕様を使うかを指定するものです。

Square APIは、機能追加や改善によって更新されます。

そのため、同じエンドポイントでも、API Versionによって入力項目や返されるデータが異なる可能性があります。

Square APIのバージョン名は、リリース日を表すYYYY-MM-DD形式です。Squareでは通常、APIとSDKのリリースが定期的に行われます。

例です。

2025-01-23
2025-04-16
2026-02-19

なぜVersionを固定するのか

ECサイトを作った日に正常に動いていたとしても、Square APIの仕様が変わる可能性があります。

そこで、使用するAPI Versionを固定します。

このECは、
この時点のSquare API仕様で動かす

Versionを固定すると、Square側に新しいAPI Versionが登場しても、自動的に破壊的変更の影響を受けにくくなります。

Developer ConsoleのデフォルトVersion

Square Developer Consoleでは、アプリケーションごとにデフォルトのAPI Versionを設定できます。

リクエストにSquare-Versionヘッダーを付けなかった場合は、そのデフォルトVersionが使われます。

Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

明示的にVersionを指定する場合は、次のようにします。

Square-Version: YYYY-MM-DD
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

Square公式では、リクエストのSquare-Versionヘッダーによって、アプリケーションのデフォルトVersionを上書きできます。

SDK Versionとの違い

Square API Versionと、Node.js SDKのバージョンは別物です。

Square API Version：
SquareのAPI仕様

Square Node.js SDK Version：
使用しているnpmパッケージのバージョン

Node.js SDKは、一般的なSemantic Versioningに従う形式です。

MAJOR.MINOR.PATCH

新しいAPI機能を使うために、Square SDKの更新が必要になる場合があります。Square公式でも、SDKごとに対応するSquare API Versionがあり、新機能を利用するときにはSDK更新が必要になることがあると説明されています。

本番運用での更新方法

API VersionやSDKは、理由なく頻繁に更新しません。

次の順番で進めます。

1. Squareのリリースノートを確認
2. 変更点を確認
3. Sandboxで動作確認
4. 決済・注文・Webhookをテスト
5. 問題がなければ本番更新

特に確認する項目です。

□ 決済リンクを作成できる
□ Paymentを取得できる
□ Orderを取得できる
□ Webhookを処理できる
□ エラー形式が変わっていない
□ SDKの型エラーがない

---

A.2のストーリーまとめ

ここまでの内容を、ECサイトがSquareへ接続する物語として整理します。

1. Square Developer Consoleでアプリを作る
        ↓
2. Application IDが発行される
        ↓
3. Personal Access Tokenを取得する
        ↓
4. 利用する店舗のLocation IDを確認する
        ↓
5. Sandbox環境へ接続する
        ↓
6. Bearer Token方式でAPIを呼び出す
        ↓
7. API Versionを固定して動作を安定させる
        ↓
8. テスト完了後、Productionへ切り替える

自社専用ECの基本構成です。

購入者
  ↓
Next.js
  ↓
サーバー側でAccess Tokenを取得
  ↓
Square API
  ↓
指定したLocationで決済・注文処理

複数のSquare事業者へサービスを提供する場合は、途中にOAuthが入ります。

Square事業者
  ↓
OAuthで連携を許可
  ↓
OAuth Access Tokenを取得
  ↓
事業者に代わってAPIを呼び出す

最後に覚えておきたいポイントです。

Application ID：
どのアプリなのかを識別する

Access Token：
Square APIへアクセスするための鍵

Location ID：
どの店舗・販売拠点の処理かを指定する

Sandbox：
お金を動かさずに試す環境

Production：
実際の販売を行う環境

OAuth：
他のSquare事業者からアクセス許可を得る仕組み

Personal Access Token：
自社Square専用システムで使うToken

Bearer Token：
Access TokenをHTTPで送る認証方式

API Version：
使用するSquare APIの仕様を固定する設定

Square APIの認証・環境設定は、次の一言にまとめられます。

正しい鍵を使い、正しい店舗を指定し、正しい環境へ接続する。

参照元

• Square Access Tokens and Other Credentials
• Square Sandbox
• Square OAuth API
• Square Locations API
• Using the Square REST API
• Versioning in the Square API
• Next.js Environment Variables