認証とスコープ
atouch API は OAuth 2.1（client_credentials） を採用しています。アクセストークンは JWT（RS256） で、Authorization: Bearer <token> で送ります。
トークンエンドポイント
POST /v1/oauth/token（application/x-www-form-urlencoded）
| パラメータ | 必須 | 説明 |
|---|---|---|
grant_type | ✓ | client_credentials（他に authorization_code / refresh_token） |
client_id | ✓ | クライアント ID |
client_secret | ✓ | クライアント秘密（confidential） |
scope | 要求スコープ（省略時はクライアント既定） |
スコープ一覧（リソース × 操作）
行＝リソース、列＝操作。セルが必要なスコープです（— は現時点で未提供）。PII 列は付与審査の厳しさ（tier）の目安。
| リソース | 参照（Read） | 書き込み（Write） | PII・tier |
|---|---|---|---|
| 商品 / カテゴリ | read_items | write_items（登録・編集・画像） | なし |
| 在庫 | read_items | write_items（絶対値 SET／増減）・write_reservations（予約→確定／解放） | なし |
| 配送会社 | read_items | — | なし |
自ショップ（/me） | read_users | — | 低 |
| 注文 | read_orders | write_shipping（出荷状況遷移・送り状の登録/訂正） | なし |
| └ 買い手 PII | read_orders_pii | — | 高（要審査） |
| 顧客 | read_customers | — | 低 |
| └ 顧客 PII | read_customers_pii | — | 最高（要審査） |
書き込みスコープ（
write_*）は 3 分類:write_reservations（在庫予約）・write_shipping（出荷状況）・write_items（商品・カテゴリー・画像・在庫）。参照スコープは 6 分類（うち*_piiの 2 つは高信頼クライアント限定）。
書き込みスコープの注意
- 書き込み系エンドポイント（
write_*）はIdempotency-Keyヘッダーが必須です。同一キーの再送は最初の結果をそのまま再生します（Idempotent-Replay: trueヘッダー付き）。 - 同一キーで異なるボディを送ると
422になります。リトライは必ず同一リクエストで行ってください。
最小権限（重要）
- クライアントには必要なスコープだけが許可されます。許可外のスコープを要求すると
400 invalid_scope（トークンが発行されません）。 - PII スコープ（
*_pii）は高信頼クライアントにのみ付与されます。
PII の redaction
PII スコープを持たないトークンでは、購入者・お届け先・顧客プロフィールの各フィールドはレスポンスに現れません（キーごと省略）。
// read_orders のみ（purchaser 無し）
{ "data": { "id": "3823", "status": "shipped", "total": {"amount":10000,"currency":"JPY"} } }
// read_orders + read_orders_pii（purchaser あり）
{ "data": { "id": "3823", "purchaser": { "last_name": "…", "tel": "…" } } }
決済のカード番号・決済代行トークンはいかなるスコープでも返しません。
トークンの失効
POST /v1/oauth/revoke（RFC 7009）で refresh token を失効できます。