認証

アプリケーションは、WinkおよびTripPay APIと通信するために使用できる認証済みOAuth2セッションを作成するために必要なClient IDとSecret Keyを提供します。

認証済みセッションを作成する手順は以下の通りです。

ステップ1. ステージングまたは本番環境でアクセストークンを取得します：

おそらく、言語に対応した強力なOAuth2ライブラリを使用しているため、ほとんどの処理はライブラリが行います。ここでは、curlを使ったコマンドラインでの最も基本的な使用例を示します。

ステージング

curl -X POST https://staging-iam.wink.travel/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<YOUR_CLIENT_ID>" \
  -d "client_secret=<YOUR_SECRET_KEY>"

本番

curl -X POST https://iam.wink.travel/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<YOUR_CLIENT_ID>" \
  -d "client_secret=<YOUR_SECRET_KEY>"

これにより、アクセストークンとその他のOAuth2レスポンスデータが返されます：

{
  "access_token": "abc123"
}

いずれかのエンドポイントにリクエストを送る際は、ヘッダーに以下を含めてください：

Wink-Version = 2.0 最新 - 他の利用可能なバージョンはAPIドキュメントをご覧ください。
Authorization = Bearer ${access_token} アクセストークンを挿入してください。

スコープ

スコープはアクセストークンに付与される権限です。トークンをリクエストする際に、scopeパラメータでスペース区切りのスコープリストを渡し、トークンはそのスコープがカバーする範囲にのみアクセスできます。client_credentialsグラントでは、トークンリクエスト時にスコープを設定します — 上記のcurl例やPostmanウォークスルーを参照してください。

スコープはsection.actionという名前で、actionは以下のいずれかです：

read — リソースの閲覧（安全なGETリクエスト）
write — リソースの作成・更新（POST / PUT / PATCH）
remove — リソースの削除（DELETE）

Winkは機能別に権限をグループ化しています。統合に必要なスコープのみをリクエストしてください：

スコープグループ	スコープ	アクセス可能な内容	リスク
アカウント	`account.read` `account.write` `account.remove`	エンティティ、チームメンバー、設定、アプリケーションの管理	低〜中
インベントリ	`inventory.read` `inventory.write` `inventory.remove`	物件、部屋タイプ、料金プラン、料金、アドオン、空室状況、アクティビティ、アトラクション	低〜中
予約	`booking.read` `booking.write` `booking.remove`	検索、閲覧、作成、キャンセル、返金、チェックアウト、キャンセルポリシー	低〜中
マーケティング	`marketing.read` `marketing.write` `marketing.remove`	キャンペーン、特典、販売チャネル、WinkLinks、管理されたソーシャル、ロイヤリティ	低〜中
コンテンツ	`content.read` `content.write` `content.remove`	物件説明、レビュー、メディア、地図、グリーンインデックス	低〜中
分析	`analytics.read` `analytics.write` `analytics.remove`	レポートと分析 — 収益、リーダーボード	低〜中
統合	`integrations.read` `integrations.write` `integrations.remove`	チャンネルマネージャー、外部予約システム、Google Hotel、通知エンドポイント、予約同期	低〜中
決済	`payment.read` `payment.write` `payment.remove`	決済処理、Stripe、Revolut、支払い、サブスクリプション	中〜高
会計	`accounting.read` `accounting.write` `accounting.remove`	会計、出金台帳、照合	中〜高
MCP	`mcp.read` `mcp.write` `mcp.remove`	AIエージェント向けのMCPトランスポート（`/mcp`）を開く	低〜中

いくつか注意点：

最小限のリクエストを。 統合で実際に使用するスコープのみをリクエストしてください — 必要以上に広範囲のアクセス権を持つトークンは、漏洩時の影響範囲が大きくなります。
不明なスコープは拒否されます。 登録されていない、または存在しないスコープをリクエストすると、トークン発行時に失敗します。
mcp.*はAIエージェントクライアント専用です。 MCPトランスポートを開くために必要であり、通常のREST API呼び出しには不要です。Model Context Protocolを参照してください。