認証

対象

このAPIは、Roktネットワーク上に構築する統合パートナー向けです。自分のチェックアウトに配置を統合するRoktのeコマースパートナーは、代わりにRokt Ecommerce開発者ドキュメントを使用してください。

Partnerships APIに認証するには、2セットのクレデンシャルが必要です：

• APIクレデンシャル: Roktがオンボーディング時にプラットフォームに一度発行する長期間有効なclient_idとclient_secret。自分で生成することはできません。まだ持っていない場合は、APIクレデンシャルを取得するを参照してください。
• JWTアクセストークン: Roktの認証エンドポイントにAPIクレデンシャルを送信して作成する短期間有効なトークン。APIクレデンシャルをアクセストークンに交換する方法を学んでください。

アクセストークンは、Partnerships APIへの呼び出しを認可します。すべてのリクエストにAuthorizationヘッダーに含めてください。書き込み時には、プラットフォームの親アカウントIDも送信してください：

Authorization: Bearer <access-token>
X-Platform-Parent-Account-Id: <your-platform-parent-account-id>

APIクレデンシャルを取得する

Roktが初期クレデンシャルを発行

自分でPartnerships APIクレデンシャルを生成することはできません。オンボーディング時にRoktがプラットフォームに発行する必要があります。これらのAPIクレデンシャルは長期間有効で再利用可能です：一時的なアクセストークンを生成するために同じクレデンシャルセットを使用します。

APIクレデンシャルをリクエストするには、smb-partnerships@rokt.comに以下をメールしてください：

• プラットフォーム名
• 予想されるマーチャントボリューム
• 割り当てられたマネージャーアカウントID

Roktは、プラットフォームのclient_idとclient_secretを返信します。これを使用してすべてのアクセストークン交換を行います。これらは一度だけリクエストします。将来のリリースでセルフサーブオプションが提供される予定です。

警告

client_secretはパスワードのように扱ってください：シークレットマネージャーに保存し、ソースにチェックインせず、ブラウザに公開しないでください。短期間有効なアクセストークンのみがPartnerships-APIに関連するものに送信されるべきです。

APIクレデンシャルをアクセストークンに交換する

Roktの認証エンドポイントにクレデンシャルをPOSTして短期間有効なJWTアクセストークンを取得します。トークンが期限切れになるため、約5分ごとにこれを繰り返します。アクセストークンをすべてのPartnerships API呼び出しでAuthorization: Bearer値として使用します。

curl -X POST 'https://auth.rokt.com/api/v1/oauth/token' \
  -H 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=rspub_xxxxxxxxxxxx' \
  --data-urlencode 'client_secret=rsec_xxxxxxxxxxxx'

標準のOAuth2クライアントクレデンシャルレスポンス：

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 300
}

すべてのPartnerships API呼び出しでaccess_tokenをAuthorization: Bearer <access_token>として渡します。expires_inは秒単位で、約5分です。

すべての呼び出しでのヘッダー

Authorizationstringrequired

Bearer <access-token>。すべてのエンドポイントで必要です。

X-Platform-Parent-Account-Idstringrequired

すべての書き込み (POST / PUT) 呼び出しで必要です。パートナープラットフォームのRokt親アカウントIDに設定し、登録時にplatform_parent_account_idボディフィールドで渡すのと同じ値です。書き込み時にこれが欠けていると422が返されます。管理アカウントの実際の親と一致しない場合は403が返されます。読み取りはヘッダーをオプションとして受け入れますが、明確にするためにすべての呼び出しで推奨されます。

Idempotency-Keyuuidrequired

すべての書き込み (POST/PUT) 呼び出しで必要です。UUID形式、24時間の重複排除ウィンドウ。冪等性を参照してください。

X-Request-Idstring

オプションの相関ID。Roktのサーバーログとレスポンスエンベロープにスレッド化したい場合は、自分の値を渡してください。サポートチケットに対する自分のログを相関させる際に便利です。省略した場合、Roktが生成し、レスポンスエンベロープのrequest_idに返します。

リクエスト例

curl

curl -i 'https://accounts.rokt.com/v1/partnership/accounts?parent_account_id=<your-platform-parent-account-id>' \
  -H "Authorization: Bearer <access-token>" \
  -H "X-Platform-Parent-Account-Id: <your-platform-parent-account-id>" \
  -H "X-Request-Id: 8f3a9c2b-1d4e-4f5a-9b6c-2e8d7a1f3b5c"

リストエンドポイントには?parent_account_id=<your-parent-id>が必要です。統合された単一アカウントGET /v1/partnership/accounts/{id}はまだ公開されていません。代わりにリソースごとの読み取り (marketplacecontrolslists, status) を使用してください。

401 vs 403 vs 422

これらの3つのエラーは異なる意味を持ちます。混同しないでください。

ステータス	意味	対処法
401 Unauthorized	アクセストークンが欠落している、期限切れである、不正な形式である、またはその署名が検証されません。	APIクレデンシャルを再交換して更新してください。失敗が続く場合、トークン発行の統合が誤って構成されています。
403 Forbidden	アクセストークンは有効ですが、(a) あなたがそのアカウントで行動する許可を持っていない（プラットフォームのアカウント間の許可設定が欠落しているか同期されていない）、または (b) 送信した X-Platform-Parent-Account-Id が管理アカウントの実際の親と一致しません。	account_id があなたのマネージャーに属していることと、ヘッダーの値が正しいことを確認してください。両方が正しいと思われる場合は、封筒から request_id を使用してサポートチケットを提出してください。
422 Unprocessable	書き込み時に必要なヘッダーが欠落しています。最も一般的には X-Platform-Parent-Account-Id。	ヘッダーを追加し、同じIdempotency-Keyで再試行してください。

アクセストークンのローテーション

アクセストークンは短いTTL（約5分）です。クライアントは各リクエストで更新するか、キャッシュして期限切れ時に更新する必要があります。アクセストークンをハードコードしないでください。また、長期間有効な client_secret をクライアントサイドコードに埋め込まないでください。アクセストークンはJWTであるため、クライアント側でデコードして、期限切れの問題をデバッグする際に exp クレームを確認できます。アクセストークンの他の部分はパートナー契約の一部ではありません。

長時間実行されるバッチジョブが 401 をバッチ中に検出した場合、APIクレデンシャルを再交換して新しいアクセストークンを取得し、再試行してください。Idempotency-Key を使用すると、24時間の重複排除ウィンドウ内で既に成功した書き込みに対してリトライが無操作に収束します。

レートリミット

APIクレデンシャルは、書き込みが多いエンドポイントでの毎分リクエストクォータをキーとします。同じ client_id を使用するフリート内のすべてのサーバーは1つのバケットを共有します。各エンドポイントの制限と 429 封筒については、Rate Limits を参照してください。