stigg-api

Stigg API — 認証、トランスポート、SDK の選択

このスキルでは、どの Stigg サーフェスを呼び出すかと、正しく認証する方法という 2 つの疑問に答えます。カタログ、エンタイトルメント、サブスクリプションの操作には、それぞれ専用のスキルを使用してください（ルーティングについては、包括的な stigg スキルを参照してください）。

始める前に

包括的な stigg スキルに従い、まず検索してください。Stigg の API は現在も開発が進められており（執筆時点では REST API はパブリックベータです）、コードを生成する前に Mintlify Stigg docs MCP / llms.txt を使って、エンドポイントの形式と SDK の初期化シグネチャを確認してください。

API キー — 知っておくべき 3 種類

各環境には 2 つのデフォルトキーが用意されます。Scale プランをご利用のお客様は、スコープ付きキーも作成できます。

種類	プレフィックス	配置場所	デフォルトのスコープ	スコープのカスタマイズ
フルアクセス（サーバー）	server-	バックエンドのみ	現在および将来のすべての権限	いいえ（変更不可）
パブリッシャブル（クライアント）	client-	ブラウザー、モバイル	読み取り専用、限定的	いいえ（変更不可）
スコープ付き（サーバー）	server-	バックエンドのみ	任意に設定	はい（リソース単位）

確認場所： Stigg アプリ → Integrations → API keys（環境ごとに個別のキーセットがあります）。

フルアクセスキー

環境ごとにデフォルトで用意されています。その環境内では制限がなく、Stigg が機能を追加すると新しい権限を自動的に継承します。環境ごとに存在できるフルアクセスキーは 1 つだけで、ユーザーが追加作成することはできません。連携の立ち上げ時にはデフォルトのバックエンドキーとして使用し、連携が成熟したら、より限定的なスコープ付きキーに切り替えてください。

パブリッシャブルキー

フロントエンド／モバイル SDK 向けに設計されています。読み取り専用で変更不可です。スコープを拡張することはできません。クライアント側のコードに含めても安全な設計ですが、本番環境ではクライアント側のセキュリティ強化を有効にしてください（HMAC SHA256 署名付き顧客トークン。パブリッシャブルキーの詳細パネルで設定します）。

フルアクセスキーまたはスコープ付きサーバーキーを、ブラウザー、公開リポジトリ、フロントエンドバンドルに絶対に含めないでください。サーバー上の環境変数を使用してください。

スコープ付きキー（Scale プラン）

明示的に制限された権限を持つ、ユーザーが作成するサーバーキーです。最小権限の原則を実践できます。漏えい時の影響範囲を小さく保つため、サービス、AI クライアント、ユースケースごとに作成してください。スコープ付きキーはプラットフォームの将来の機能を継承しません。新しいリソースへのアクセス権は手動で付与する必要があります。

カスタム権限スコープの一覧（スコープ付きキーの作成時に選べるプリセット）：

• フルアクセス — 環境内のすべてのリソースに対する読み取り／書き込み。
• 読み取り専用 — すべてのリソースの読み取り。書き込み不可。
• 顧客の書き込み — 顧客データの管理。
• サブスクリプションの書き込み — サブスクリプションの作成／更新。
• クーポンの書き込み — 割引／クーポンのロジックの管理。
• API キーの読み取りと書き込み — API キーのプログラムによる管理。
• イベントキューの読み取り — 一時的な SQS イベントキュー認証情報の取得（読み取り専用。このリソースには書き込み操作がありません）。

リソースで書き込みを選択すると、そのリソースの読み取り権限も暗黙的に付与されます。

キーのローテーション

Integrations → API keys でキーのコンテキストメニュー（⋮）を開き、Rotate key を選択します。猶予期間（Now / 1h / 24h / 3d / 7d）を選んでください。古いシークレットは猶予期間が終了するまで有効です。ゼロダウンタイムでのローリングデプロイを想定した設計です。さらに時間が必要な場合は、古いキーの有効期限が切れる前にChange grace periodを選択してください。

キーの失効は即時に行われ、取り消せません。まず、すべてのサービスを新しいキーに切り替えてください。

完全なリファレンス： references/auth.md。

適切なトランスポートを選ぶ

対象	使用する場面
Node SDK（@stigg/node-server-sdk）	Node／TypeScript での本番環境のホットパス向けです。バックエンドではデフォルトの選択肢です。 ほかのバックエンドランタイム（Python、Go、Java、Ruby、.NET、Sidecar）にも SDK が用意されています。詳しくはdocs.stigg.ioをご覧ください。パターンは似ていますが、正確なフィールド名は異なる場合があります。
Frontend SDK（React／Next.js 用の @stigg/react-sdk、バニラ JS 用の @stigg/js-client-sdk）	ブラウザーでペイウォール、顧客ポータル、またはエンタイトルメントのチェックを表示する場合です。
REST API（https://api.stigg.io/api/v1）	使用言語の SDK がない場合、薄いサーバーサイドプロキシを使う場合、または明示的な制御が必要な場合です。
GraphQL API（https://api.stigg.io/graphql）	既存の GraphQL 統合がある場合、または REST API ではまだ公開されていないクエリを使う場合です。
Stigg MCP server（https://mcp.stigg.io）	AI を活用した開発向けです。stigg-mcpをご覧ください。
Stigg CLI（Go バイナリ — brew install stiggio/tools/stigg、リポジトリ：https://github.com/stiggio/stigg-cli）	スクリプト、CI/CD 向けです。オプトインのみです。デフォルトとオプトインの方針については、stigg-mcp/references/cli-vs-mcp.mdをご覧ください。

エッジケースを含む判断フローチャートについては、stigg/references/decision-tree.mdをご覧ください。SDK の選択（Node + React を標準とし、Node 以外のランタイムでは生の HTTP を使用）については、references/sdk-selection.mdをご覧ください。

REST API — クイックリファレンス

• ベース URL： https://api.stigg.io/api/v1
• 認証ヘッダー： X-API-KEY: <YOUR_SERVER_KEY>
• Content-Type： リクエストボディには application/json を指定します。
• 冪等性： POST リクエストに Idempotency-Key: <unique-id> を追加します（24 時間キャッシュされます）。同じキーで繰り返し呼び出すと、キャッシュされたレスポンスが返されます。
• ページネーション： カーソルベースです。クエリパラメーター：limit（デフォルト 20、最大 100）、starting_after、ending_before。レスポンスには data[]、has_more、next_cursor が含まれます。
• フィルタリング： リソース固有のクエリパラメーターを使用します。列挙型の値を取るフィルターには、基になる列挙型のシンボル（大文字）を指定します。ほとんどのリストエンドポイントでは、複数の値をカンマ区切りで指定してフィルタリングできます。例：[email protected]、?status=ACTIVE,IN_TRIAL、?pricingType=PAID。日付フィールドでは範囲演算子を使用できます（?createdAt[gte]=2026-01-01T00:00:00Z）。
• エラー： 標準の HTTP ステータスコードと構造化されたボディが返されます。

# Authenticated GET
curl -X GET "https://api.stigg.io/api/v1/customers" \
  -H "X-API-KEY: $STIGG_SERVER_API_KEY" \
  -H "Content-Type: application/json"

# Idempotent POST
curl -X POST "https://api.stigg.io/api/v1/customers" \
  -H "X-API-KEY: $STIGG_SERVER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: bootstrap-customer-acme-001" \
  -d '{ "id": "customer-123", "name": "Acme Corp", "email": "[email protected]" }'

金額 — セントではなく、通貨単位で指定

Stripe を利用している方は特にご注意ください： Stigg では金額を通貨の単位で表します。最小通貨単位ではありません。49 は 0.49 ドルではなく、49.00 ドルを意味します。3990 は 39.90 ドルではなく、3,990 ドルを意味します。

Stripe の規約は逆で、金額を最小通貨単位（USD ではセント）で表します。Stigg に値を渡すときに 100 を掛けたり、取得した値を読み取るときに 100 で割ったりしないでください。これはプラン価格、請求金額、クレジット付与の cost_basis、請求書プレビューの subtotal／total／discount／tax フィールドなど、すべての金額フィールドに適用されます。

エラーの意味

ステータス	意味
200	成功 — ボディにリソースが含まれます
201	作成済み
400	不正なリクエスト — パラメーターまたはボディが無効です
401	認証されていません — X-API-KEY がないか、無効です
403	アクセスが禁止されています — 認証済みですが、キーに必要なスコープがありません
404	見つかりません
409	競合 — 例：サブスクリプションがすでに存在します
429	リクエストが多すぎます — レート制限をご覧ください

事前に知っておくべき REST API の注意点が 2 つあります（変更されている可能性があるため、ページ上で再確認してください）。

• GET /api/v1/subscriptions は、各項目の subscriptionEntitlements を含みません。大規模な環境ではコストが高すぎるためです。詳細なエンタイトルメントを取得するには、GET /api/v1/subscriptions/{id} を使用してください。
• 単一のサブスクリプションに含まれる subscriptionEntitlements は、オーバーライドのみであり、プランから継承したエンタイトルメント全体ではありません。プランのエンタイトルメント全体を取得するには、GET /api/v1/plans/{planId}/entitlements を呼び出してください。

GraphQL API — クイックリファレンス

• エンドポイント： https://api.stigg.io/graphql
• 認証ヘッダー： X-API-Key: <YOUR_SERVER_KEY>
• 使用する場面： 既存の統合や、REST ではまだ公開されていないクエリには GraphQL を引き続き使用してください。新規開発ではREST を優先してください。

curl -X POST https://api.stigg.io/graphql \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $STIGG_SERVER_API_KEY" \
  -d '{"query":"{ customers { edges { node { customerId name } } } }"}'

SDK — 初期化スニペット

ランタイムに合った SDK を必ず選択してください。全体の対応表：references/sdk-selection.md。

バックエンド（Node）— @stigg/node-server-sdk：

import Stigg from '@stigg/node-server-sdk';

const stigg = await Stigg.initialize({
  apiKey: process.env.STIGG_SERVER_API_KEY!,
});

フロントエンド（React）— @stigg/react-sdk：

import { StiggProvider } from '@stigg/react-sdk';

<StiggProvider apiKey="<STIGG_CLIENT_API_KEY>" customerId="<LOGGED_IN_CUSTOMER_ID>">
  {children}
</StiggProvider>

バニラ JS のフロントエンドでは @stigg/js-client-sdk（同期的な Stigg.initialize(...) と await client.waitForInitialization()）を使用します。その他のランタイム（Python、Go、Java、Ruby、.NET、Sidecar、Vue、Embed）については、概要と docs.stigg.io へのリンクが記載されている references/sdk-selection.md を参照してください。REST ベースで自動生成された TypeScript SDK（@stigg/typescript）は現在ベータ版です。GA に達するまでは @stigg/node-server-sdk を引き続き使用してください。

レート制限

Stigg は環境ごと、エンドポイントごとにレート制限を適用します。本番環境のホットパスでは、バックオフを伴う 429 への対処が必要です。現在の制限と「Using Stigg at Scale」のガイダンスは docs.stigg.io にあります。運用上の原則については references/rate-limits.md に概要が記載されています。

認証エラー — 迅速な診断

症状	考えられる原因	修正方法
すべてのリクエストで 401 Unauthenticated が発生する	ヘッダー名のタイプミス（X-API-KEY ではなく Authorization を指定している）	X-API-KEY を正確に指定してください。
POST リクエストのみ 401 が発生する	Content-Type が未設定、または誤っているため、認証前にゲートウェイで拒否されている	Content-Type: application/json を設定してください。
キーのローテーション後に 401 が発生する	古いキーの猶予期間が過ぎている	サービスを新しいキーに切り替えてください。
403 Forbidden が発生する	スコープ付きキーにリソースへの権限がない	不足している権限を付与するか、より広い範囲のキーを使用してください。
フロントエンド SDK に他の顧客のデータが表示される	クライアント側の強化が不足している	公開可能キーで HMAC 署名付き顧客トークンを有効にしてください。
本番環境の「Stigg」呼び出しがサンドボックスに到達する	環境設定のキーが誤っている	キーは環境に紐付いています。確認して置き換えてください。

このスキルを使わない場合

• ペイウォール／顧客ポータルの UI を構築する場合 — stigg-widgets を使用してください。
• 機能／プラン／アドオンをモデル化する場合 — stigg-pricing-modeling を使用してください。
• イベント形式と測定形式のどちらで使用量をレポートするかを決める場合 — stigg-entitlements を使用してください。
• MCP を初めてインストールする場合 — stigg-mcp を使用してください。

よくある間違い

間違い	修正方法
server- キーをフロントエンドアプリに設定する	client- の公開可能キーを使用してください。
フルアクセスキーをあらゆる場所にハードコードする	サービスごとにスコープ付きキーを作成してください。
顧客／サブスクリプションの POST に Idempotency-Key がない	設定してください。Stigg はレスポンスを 24 時間キャッシュするため、再試行しても安全です。
subscriptionEntitlements をすべての権限情報として扱う	これはオーバーライドのみです。すべての一覧にはプランのエンドポイントを使用してください。
GET /subscriptions を呼び出して、権限情報が返されることを期待する	設計上、返されません。行ごとに GET /subscriptions/{id} を使用してください。
新しいコードで REST と GraphQL を混在させる	どちらかを選択してください（デフォルトは REST）。理由がない限り、ハイブリッド構成にしないでください。