認証
- Authorization: ApiKey
- API キーは POST /api/v1/auth/token の Authorization ヘッダーだけに指定します。 JSON、URL、クエリパラメーターには含めないでください。
- Authorization: Bearer
- リソースへのリクエストには返されたトークンを使い、expires_at に従って更新します。 expires_in の単位は秒です。
なぜ最初にトークンを取得するのですか？
APIキーを使ってトークンを取得します。トークンは15分間有効で、複数のリクエストに利用できます。リソースへのリクエストには、Authorization: Bearerヘッダーでトークンだけを送信します。
通常のリクエストにAPIキーは含まれません。トークンだけが漏えいした場合、利用できるのは有効期限までです。ただし、APIキーが盗まれると、新しいトークンを取得される可能性があります。
トークンの有効期間は？
- expires_in
- 発行から900秒、つまり15分です。リクエストを送信しても有効期間は延長されません。
- expires_at
- UTCで表される有効期限です。現在のアクセス制限によって、それより前に利用が拒否される場合があります。
新しいトークンはいつ取得しますか？
同じトークンを複数のリクエストで再利用し、expires_atより前に次のトークンを取得してください。操作のたびに取得する必要はありません。新しいトークンの取得にはAPIキーを使います。
アクセス拒否と再試行
- 401
- 401は必ずしもトークンの期限切れを意味しません。期限切れの場合は新しいトークンを取得し、読み取りを最大1回だけ再試行してください。トークン取得で401が返る場合は、キーを確認して自動試行を停止してください。
- 403
- 403の場合は権限、IP制限、プランを確認してください。新しいトークンを取得しても、取り消されたアクセス権は復元されません。
IP 制限
- アクセストークンでも、キーの現在の権限、ストアの利用権限、失効、IP 制限を回避できません。
- 必要に応じて、キーを連携元のアドレスに制限してください。
- 管理者はこのリストを編集でき、最大32件のアドレスを登録できます。
キーの管理
- API キーの管理権限は、連携のリソース権限とは別です。
- キーの閲覧、作成、編集、削除の管理権限をグループに付与できるのは owner だけです。
- 許可されたグループのメンバーは、そのグループに付与された操作だけを実行できます。
レート制限
Engine ≥ 4.143.0. トークンの各応答には、発行時の店舗ポリシーに基づく data.rate_limits が含まれます。すべてのキーで上限を共有し、新しいトークンでもリセットされません。プラン変更はトークンの有効期限前に適用される場合があります。
- read_per_minute
- 1分あたりの読み取りリクエスト数。
- write_per_minute
- 1分あたりの書き込みリクエスト数。この値は書き込み権限を付与しません。
- auth_per_minute
- 認証失敗を含む、1分あたりのトークンリクエスト数。