認証とスコープ

すべてのパブリックAPIリクエストは、長期間有効なAPIキーをベアラートークンとして運ぶ必要があります。スコープは各キーが実行できる内容を制約します — 統合が実際に必要とするものだけを付与してください。

ベアラートークン形式

APIキーは次のようになります:

scs_live_t9JQ10cDjddmslzv9mRKYqaDS5ZU1KuDH

プレフィックスscs_live_は、キーがSecureCodingHubのプロダクション認証情報であることを識別します。トークンの合計は41文字 (9文字のプレフィックス + 32文字のランダムボディ) です。キー作成時に1回のみ返されます。

標準のベアラー認証ヘッダーとして、すべてのリクエストでトークンを送信してください:

Authorization: Bearer scs_live_t9JQ10cDjddmslzv9mRKYqaDS5ZU1KuDH

APIキーの作成

APIキーはAPIではなく管理コンソールで作成します。

組織管理者としてapp.securecodinghub.comにサインインします。

サイドバーから組織 → APIキーを開きます。

+ 新規キーを作成をクリックします。キーに分かりやすい名前 (例: GitHub Actions — CIやLooker BI sync) を付けます。

統合に必要なスコープのみをチェックします。読み取り専用スコープは青、書き込みスコープは琥珀色でハイライトされます。

(任意) 有効期限を設定します。有効期限のないキーは、取り消すまで有効です。

キーを作成をクリックします。完全なトークンはモーダルに表示されます。今すぐシークレットマネージャーにコピーしてください。再取得することはできません — プレフィックスと最後の4文字のみが保存されます。

スコープリファレンス

SecureCodingHubは、読み取り階層と書き込み階層に分かれた16個の細粒度スコープを使用します。一致するスコープなしでエンドポイントに到達したリクエストは、レスポンスボディ{"error":"insufficient_scope","required":"…","present":[…]}とともに403 Forbiddenを返します。

スコープ	リソース	階層	付与権限
`org:read`	組織	読み取り	組織メタデータ (名前、プラン、シート) を読み取ります。
`users:read`	ユーザー	読み取り	ユーザーをリスト表示、ユーザー詳細を取得します。
`users:write`	ユーザー	書き込み	ユーザーを作成、更新、非アクティブ化します。
`teams:read`	チーム	読み取り	チームとメンバーをリスト表示します。
`teams:write`	チーム	書き込み	チームを作成、更新、削除します。
`assignments:read`	課題	読み取り	課題をリスト表示、完了状況を含む詳細を取得します。
`assignments:write`	課題	書き込み	課題を作成、更新、非アクティブ化します。
`custom-courses:read`	カスタムコース	読み取り	アイテム付きのカスタムコースをリスト表示します。
`custom-courses:write`	カスタムコース	書き込み	カスタムコースを作成、更新、削除します。
`progress:read`	進捗	読み取り	ユーザーごとの練習と学習の進捗を取得します。
`certificates:read`	証明書	読み取り	証明書をリスト表示してダウンロードします。
`audit-log:read`	監査ログ	読み取り	監査ログエントリをリスト表示します。
`compliance:read`	コンプライアンス	読み取り	コンプライアンスダッシュボードデータを取得します。
`content:read`	コンテンツ	読み取り	トピック、シナリオ、CWE-to-topicマッピングを取得します。
`sarif:ingest`	SARIF	書き込み	SARIF実行を取り込み、トレーニングを自動割り当てします。
`webhook:manage`	Webhook	書き込み	アウトバウンドWebhookエンドポイントを管理します。

推奨スコープセット

ユースケース	最小スコープ
CI/CD SARIF取り込み	`sarif:ingest`
HR駆動のユーザープロビジョニング	`users:write`, `teams:write`
BI / レポートエクスポート	`users:read`, `progress:read`, `assignments:read`, `audit-log:read`
チケッティングとSOAR (イベントサブスクライバー)	`webhook:manage`, `assignments:read`
監査人読み取り専用エクスポート	`org:read`, `audit-log:read`, `compliance:read`, `certificates:read`

ローテーションと取り消し

キーをローテーションするには、まず置き換え用のキーを作成し、新しいトークンをデプロイしてから、組織 → APIキーで古いキーを取り消してください。取り消しは即座に有効になります — 古いトークンを使用中のリクエストは数秒以内に401 Unauthorizedを返し始めます。

キーが漏洩した場合は取り消してください。「一時停止」状態はありません。取り消しは永続的です。トークンを再度有効化することはできません。

保管のベストプラクティス

トークンはデータベースパスワードと同じように扱ってください。ソース管理にコミットしないでください。
プラットフォームのネイティブシークレットストア (AWS Secrets Manager、GCP Secret Manager、GitHub Actions secrets、Vault、1Password Connect) を優先してください。
CIでは、必要なステップでのみトークンを注入し、echoは避けてください。
個別に取り消せるよう、統合ごとに1つのキーを発行してください。CI、BI、SOARで1つのキーを共有しないでください。
短期間の統合 (概念実証、ベンダー評価) 用に作成したトークンには有効期限を設定してください。

一般的なエラー

ステータス	レスポンス	意味
`401`	`{"error":"unauthorized"}`	トークンが欠落、不正、取り消し済み、または期限切れです。
`403`	`{"error":"insufficient_scope",…}`	トークンは有効ですが、このエンドポイントに必要なスコープが不足しています。
`429`	`{"error":"rate_limited"}`	1分あたりまたは1時間あたりの上限に達しました。レート制限を参照してください。