API によるログイン、トークン、顧客アカウント

🌐 言語: 🇻🇳 Tiếng Việt · 🇬🇧 English · 🇯🇵 日本語（現在）

API によるログイン、トークン、顧客アカウント

はじめに

このページでは、アプリが GP247 の API にログインし、ログイン状態を安全に保つ方法を説明します：トークンの取得、有効期限、ログイン試行回数の制限、 リフレッシュトークン、端末ごとのセッション管理、二要素認証、そして顧客アカウントが API でできること（会員登録、パスワードを忘れた場合、プロ フィール、住所録）です。モバイルアプリ、顧客向け Web サイト、管理ツールを作る開発者向けです。まだ API を一度も呼んだことがない場合は、 クイックスタートから始めてください。

認証（API へのログイン）

GP247 は Laravel Sanctum を使ってトークン（「入場券」の役割をする長い文字列）を発行します。 仕組みは両グループで共通です。

  1. アプリがログイン情報を login エンドポイントに送ります。管理者は username ＋ password を api/v2/core/login に、 顧客は email ＋ password を api/v2/front/login に送ります。

  2. 正しければ、システムは data キーの中に access_token（Bearer 形式のトークン）と有効期限 （expires_at、および秒単位の expires_in）を返します。

  3. 以降、ログインが必要なリクエストには、このトークンを ヘッダー に付けて送ります。

    Authorization: Bearer <access_token>

  4. 終了するときは POST logout を呼び、現在のセッションをサインアウトします（古いトークンとそのリフレッシュトークンはすぐに使えなくなります）。

権限の範囲（scope / ability）

各トークンには、誰のトークンかを示す権限の範囲が付きます。

Scope 意味
admin 管理者のトークン（Core API）
admin-supper administrator ロールを持つ管理者のトークン（Core API）
user 会員のトークン（Front API）

ℹ️ 対応バージョン: gp247/core 3.2.3 — scope はアカウントの種類だけを区別します。どのデータを見られるかは、 アカウント自身の権限設定で決まります（Core API の権限とデータの範囲）。scope user-guest は発行されなくなりました。 ロックされている顧客アカウントはログインできません。

トークンの有効期限

ℹ️ 対応バージョン: gp247/core 3.2.3

すべてのトークンには有効期限（expires_at）があります。

トークンの種類 remember_me を送らない場合 remember_me = true を送る場合
管理者 7 日（GP247_API_TOKEN_EXPIRE_ADMIN_DEFAULT） 30 日（GP247_API_RECOMMEMBER_ADMIN）
会員 7 日（GP247_API_TOKEN_EXPIRE_DEFAULT） 30 日（GP247_API_RECOMMEMBER）

with_refresh: true を付けてログインすると、アクセストークンの有効期間は 60 分だけになり、更新用のリフレッシュトークンが 付きます（リフレッシュトークン — 短命なトークンでサインイン状態を保つ）。モバイルアプリにはこの方法をおすすめします。

ℹ️ 対応バージョン: gp247/core 3.3.0 — 環境変数に正しい綴りの名前ができました：GP247_API_REMEMBER、 GP247_API_REMEMBER_ADMIN、GP247_API_SCOPE_ADMIN_SUPER。旧名（GP247_API_RECOMMEMBER など）も引き続き使えます。 両方を設定した場合は新しい名前が優先されます。php artisan gp247:doctor は、まだ使われている旧名を報告します （チェック項目 api_config_legacy_names）。scope admin-super を持つトークンも、admin-supper と同様に受け付けられます。

期限切れのトークンは 401 を返します。その場合は refresh（with_refresh 付きでログインした場合）または login を呼んで 新しいトークンを取得してください。期限切れから長く経った（7 日を超えた）トークンは、同じアカウントが次にログインしたときに 自動で削除されます。cron は不要です。

ℹ️ 対応バージョン: gp247/core 3.4.0 — 3.2.3 より前に発行されたトークン（当時は有効期限がありませんでした）には、 php artisan gp247:update を実行したときに有効期限が設定されます。トークンの実際の経過日数に「remember」の期間 （管理者: GP247_API_REMEMBER_ADMIN、会員: GP247_API_REMEMBER）を加えた日時ですが、アップグレードから 7 日より早くはなりません。古いトークンを持つアプリには、再ログインが必要になるまで少なくとも 7 日あります。 アプリが 401 を受けたら login を呼ぶようにしておいてください。

ℹ️ 対応バージョン: gp247/core 3.6.0、gp247/shop 3.4.0 — 顧客のパスワードを変更または再設定すると（ウェブサイトでも API でも）、 その顧客のすべてのトークンが無効になります。管理者も同様です：ユーザー画面、アカウント設定、または 「パスワードを忘れた場合」でパスワードを変更すると、その管理者のすべての API トークンが無効になります。

ログイン試行回数の制限

ℹ️ 対応バージョン: gp247/core 3.2.3

パスワードの総当たりを防ぐため、api/v2/core/login、api/v2/front/login と管理画面のログインフォームは試行回数を制限しています。 管理画面のログインフォームと api/v2/core/login は同じカウンターを共有し、一方での失敗はもう一方にも数えられます。

制限 既定値 変更する環境変数
アカウントごと（同じ IP から） 1 分あたり 5 回 GP247_LOGIN_THROTTLE（形式 回数,分）
IP ごと（すべてのアカウント合計） 1 分あたり 20 回 GP247_LOGIN_IP_THROTTLE

⚠️ gp247/core 3.5.0 で名称変更: 旧名 GP247_API_LOGIN_THROTTLE と GP247_API_LOGIN_IP_THROTTLE は 読み込まれなくなりました。設定している場合は .env で名前を変更してください。変更しない場合は上記の既定値が使われます。

制限を超えると → HTTP 429 と Retry-After ヘッダー（待つ必要がある秒数）が返ります。 正しくログインすると、そのアカウントのカウンターはリセットされます。 このほか、すべての API エンドポイントには 1 分あたり 1000 回の共通制限があります（GP247_API_THROTTLE）。ログイン済みなら アカウントごと、未ログインなら IP ごとに数えます。

ℹ️ 対応バージョン: gp247/core 3.8.0 — それ以前は共通制限を IP ごとに数えていたため、同じネットワーク（携帯回線や オフィスの NAT）の背後にいる多くのアプリ利用者が 1 つのカウンターを共有していました。複数のツールが 1 つのアカウントを共有 している場合は、今後そのカウンターを共有します — ツールごとにアカウントを分けるか、GP247_API_THROTTLE を引き上げてください。

顧客アカウントとサインインセッション

ℹ️ 対応バージョン: gp247/core 3.6.0、gp247/shop 3.4.0

ショッピングアプリは api/v2/front で顧客アカウントの一連の操作をすべて行えます。ルールはウェブサイトのフォームと同じ です：必須項目、カスタム項目、パスワードの強度、captcha はすべてストアの設定に従います。エンドポイントの一覧は Front API（ストアフロント）の処理の流れ にあります。

会員登録、パスワードを忘れた場合、プロフィール、住所録

  • POST register — 登録フォームと同じ項目（first_name、email、password、password_confirmation、 およびストアで有効にした address1、phone などの項目）を送ります。成功すると HTTP 201 で、customer と login と 同じトークンを返します。顧客は自分の status を設定できません。パスワードは必須です。password がない、 または空の場合は 422（errors.password）で、アカウントは作成されません。
  • POST password/forgot — パスワード再設定メールを送ります。メールアドレスにアカウントがあってもなくても常に {"data": {"sent": true}} を返すため、どのメールアドレスが登録済みかを調べることはできません。
  • POST password/reset — email、token（メールに記載）、password、password_confirmation を送ります。成功すると 顧客のすべての API トークンが無効になります。アプリは新しいパスワードで login を呼びます。
  • GET / PUT member/profile — email_verified、email_verification_required、既定の住所を含むプロフィール。 ここではパスワードを変更できません。
  • PUT member/password — password_old、password、password_confirmation を送ります。呼び出したセッションは サインインしたまま、ほかのすべての端末はサインアウトされます。古いパスワードの誤りはアカウントのログイン制限に数えられます。 新しいパスワードがない、または空の場合は 422（errors.password）で、古いパスワードはそのままです。

ℹ️ 対応バージョン: gp247/shop 3.5.0 — register と member/password は常にパスワードが必要です（以前は password キーのない本文に HTTP 500 が返り、空のパスワードは受け付けられていました）。必須項目のない JSON 本文には常に 422 を返します。

  • member/address — 住所の追加／編集／削除。"default": true を送ると既定の住所になります。既定の住所は削除できません （HTTP 422）— 先に別の住所を既定にしてください。
  • POST member/email/verify — ストアで メールアドレスの確認を必須にする がオンのとき、確認メールを再送します。顧客は どのブラウザーでもメールのリンクをクリックすれば完了します。ウェブサイトへのサインインは不要です。

register、password/*、member/email/verify には専用の制限があります：IP ごとに 1 分あたり 5 回 （GP247_API_ACCOUNT_THROTTLE、形式は 回数,分）。

⚠️ ストアが 会員登録 または パスワードを忘れた場合 のページで captcha をオンにしている場合（Captcha タブ）、API でも 使用中の captcha プラグインの項目が必要です — ない／誤り → 422（errors.captcha_field）。アプリは captcha 提供元の SDK で回答を取得するか、管理者がそのページの選択を外します。

リフレッシュトークン — 短命なトークンでサインイン状態を保つ

login、register、login/challenge に with_refresh: true（任意で device_name）を送ります：

with_refresh なし with_refresh あり
アクセストークン 7 日（remember_me で 30 日） 60 分（GP247_API_ACCESS_MINUTES）
リフレッシュトークン — 顧客 30 日（GP247_API_REFRESH_DAYS）、管理者 7 日（GP247_API_REFRESH_ADMIN_DAYS）、サインイン時から

アクセストークンが期限切れ（401）になったら、{"refresh_token": "…"} で POST refresh を呼ぶと新しいトークンの組を 受け取れます。リフレッシュトークンは1 回だけ使えます：

  • 使用済みのリフレッシュトークンを再送 → 401 refresh_token_reused となり、セッション全体がサインアウトされます （トークンが盗まれた兆候）。
  • 例外：10 秒以内の再送（不安定な通信、重複リクエスト）→ 409 refresh_in_progress、セッションは残ります。アプリでは refresh を並行ではなく1 つずつ呼んでください。
  • リフレッシュしてもセッションの期限は延びません。期限が切れたら再度サインインしてください。
curl -X POST "https://shop.example.com/api/v2/front/login" -H "Content-Type: application/json" \
  -d '{"email":"customer@example.com","password":"Secret#123","with_refresh":true,"device_name":"Hanako の iPhone"}'
curl -X POST "https://shop.example.com/api/v2/front/refresh" -H "Content-Type: application/json" \
  -d '{"refresh_token":"<受け取った refresh_token>"}'

サインインセッションの管理

サインインはそれぞれ 1 つのセッションです。GET member/sessions（顧客）と GET sessions（管理者）は、端末名、IP、 最終利用日時、どれが現在のセッションか（current）を一覧表示します。DELETE …/sessions/{id} で 1 台の端末をサインアウト します。POST logout は現在のセッションをリフレッシュトークンも含めてサインアウトします。パスワードを変更すると（顧客でも 管理者でも、ウェブサイトでも API でも）、そのアカウントのすべての API セッションとトークンがサインアウトされます。使用中の ウェブサイトのセッションはそのままです。

プラグインによる二要素認証（MFA）

core 自体は OTP コードを送りません。セキュリティプラグインが確認ステップを追加できます。その場合、正しいパスワードでの login は次のように応答します：

{ "error": 1, "code": "challenge_required", "msg": "…",
  "challenge": { "ticket": "…", "method": "totp", "meta": {}, "expires_in": 300 } }

アプリはユーザーにコードを尋ね、ticket とプラグインが求める項目（例：code）を付けて POST login/challenge を呼びます。 チケットは 1 回限りで 5 分で失効し、誤ったコードはログイン制限に数えられます（API v1 にはこのステップが ありません — API v1 を参照）。GP247 の無料 MFA プラグイン （2.3.0 から）は、二要素認証を有効にした顧客と管理者に対してこの仕組みを使います（TOTP またはリカバリーコード）。プラグイン開発者は API の作り方 — セクション 7 を参照してください。

管理 API のアクセスログ

Core API の呼び出し（login を除く）はすべて管理画面の操作ログに記録されます — 管理画面での操作と同じく、 ユーザー、パス、IP、端末を記録し、パスワード／キーは伏せられ、レスポンス本文は保存されません。権限不足で拒否された呼び出し （403）も記録されます。管理画面のログと一緒にオフにできます（GP247_ADMIN_LOG=0）。API を頻繁に呼ぶ同期ツールではログが 早く増えます — 操作ログ画面で定期的に削除してください。

よくある質問（Q&A）

Q1: トークンはどこで取得し、どのくらい有効ですか？

→ トークンは login エンドポイントが発行します。既定では 7 日後に失効し、remember_me = true を送ると 30 日になります。 認証（API へのログイン） の環境変数で変更できます。モバイルアプリは with_refresh: true でサインインし、60 分のトークンをリフレッシュ トークンで更新することをおすすめします（リフレッシュトークン — 短命なトークンでサインイン状態を保つ）。安全にログアウトするには、現在のトークンで POST logout を呼びます。 そのセッションはサインアウトされ、トークンは再利用できなくなります。

Q2: モバイルアプリはリフレッシュトークンを使うべきですか？

→ 使うべきです。with_refresh: true を付けてログインします：メインのトークンは 60 分しか有効でなく、アプリがリフレッシュトークンで新しいトークンを自動で取得するので、顧客は 再ログインする必要がなく、漏れたトークンも短時間しか使えません。

Q3: パスワードを変更すると、使用中のトークンはまだ使えますか？

→ 使えません。パスワードを変更または再設定すると（Web サイトでも API でも）、そのアカウントのすべてのトークンが無効になり、アプリは再ログインが必要です。

📅 最終更新: 2026-11-03 · ✍️ 作成者 (Author): GP247