APIキー
API キーを作成して、外部システムを統合したり、カスタム ダッシュボードを構築したり、Balla Stats データを使用してワークフローを自動化したりできます。
前提条件
API キーを作成する前に、以下が必要です。
- Balla Stats アカウント
- PROプラン以上
プランの制限: FREE = 0 キー、PRO = 3 キー (1,000 要求/時)、チーム = 10 キー (10,000 要求/時)、エンタープライズ = 50 キー (100,000 要求/時)。
API キーを作成して、外部システムを統合したり、カスタム ダッシュボードを構築したり、Balla Stats データを使用してワークフローを自動化したりできます。
範囲指定されたアクセス許可
きめ細かなアクセス制御
レート制限
キーごとのリクエスト制限
使用状況の追跡
完全な監査証跡
- API キーに移動します
- 最初のキーを作成する
- 安全にコピーして保存
- API キーを使用する
- 使用状況を監視する
- キーをローテーションまたは取り消す
ダッシュボードのサイドバーで、「API キー」「」をクリックします。このページには既存のキーがすべて表示され、新しいキーを作成できます。

「API キーの作成」 をクリックし、わかりやすい名前を入力して、キーに必要なスコープを選択します。利用可能なスコープは次のとおりです。 read, write, matches, players, teams, seasons, and stats.

読み取り専用スコープから開始し、必要な場合にのみ書き込み権限を追加します。これは最小特権の原則に従います。
キーは balla_sk_[64 の 16 進数文字] の形式で表示されます。完全なキーが表示されるのはこのときだけです。すぐにコピーして安全な場所に保管してください。

API キーは 1 回だけ表示されます。 今すぐコピーして安全に保管してください。後から取り出すことはできません。紛失した場合は、キーをローテーションするか、新しいキーを作成する必要があります。
API キーを HTTP リクエストの Authorization ヘッダーに含めます。
curl -H "Authorization: Bearer balla_sk_..." \
https://api.ballastats.com/api/matchesまたは JavaScript では次のようになります。
const response = await fetch(
'https://api.ballastats.com/api/matches',
{
headers: {
'Authorization': 'Bearer balla_sk_...',
'Content-Type': 'application/json',
},
}
);
const data = await response.json();すべてのエンドポイントは /api-docs に文書化されています。詳細については、API Documentation チュートリアルを参照してください。
キーが最後に使用されたタイムスタンプ、合計リクエスト数、および現在のレート制限ステータスを表示します。使用状況統計は、統合がどのように実行されているか、およびいつプランをアップグレードする必要があるかを理解するのに役立ちます。

Rotate キーを使用して、名前、スコープ、設定を維持しながら新しいキーを作成します。古いキーはすぐに取り消されます。 Revoke はキーを永久に非アクティブ化します。取り消されたキーを再アクティブ化することはできません。
キーをローテーションすると、古いキーはすぐに無効になります。ダウンタイムを回避するために、ローテーションの前に新しいキーで統合を更新してください。
わかりやすい名前を使用する
各キーの目的を簡単に識別できるように、「Dashboard Bot」や「Stats Exporter」などのわかりやすい名前を使用します。
最低特権
最小特権の原則に従い、統合に実際に必要なスコープのみを付与します。
定期的な回転
セキュリティのためにキーを定期的に (90 日ごと) ローテーションします。重要な衛生状態を常に把握するためのリマインダーを設定します。
キーを決して公開しないでください
API キーをソース コードにコミットしたり、プレーン テキストで共有したりしないでください。環境変数またはシークレット マネージャーを使用します。
401 不正
- キーが非アクティブ、取り消されている、または期限切れになっている可能性があります
- キーが Authorization ヘッダーに含まれていることを確認します
- ヘッダー形式が
Bearer balla_sk_...であることを確認します。
403 禁止
- キーにはこのエンドポイントに必要なスコープがありません
- キーを編集して必要なスコープを追加します (例: POST リクエストの場合は
writeを追加します) - 各エンドポイントに必要なスコープの API ドキュメントを確認してください
429 リクエストが多すぎます
- 現在の時間のレート制限を超えています
- レート制限ウィンドウがリセットされるまで待つか、プランをアップグレードして制限を引き上げてください
- いつ再試行できるかについては、
Retry-Afterヘッダーを確認してください。