APIキー
APIキーはサーバーをNU Signal Partners APIに認証します。パートナー申請の承認後、WebコンソールなしでAPIエンドポイントから直接キーを発行、ローテーション、失効できます。
最初のキーを取得（ブートストラップ）
承認後、申請状態の認証情報でPOST /partner-applications/claimを呼び出し、一度だけ使える承認トークン（プレフィックスnsp_appr_、72時間有効）を取得します。APIキーがまだないため、このエンドポイントだけが公開され、そのトークンで保護されます。最初のSandboxキーに交換してください:
curl -X POST https://signal-partners.newunivers.ai/v1/api-keys/bootstrap \
-H "Content-Type: application/json" \
-d '{ "approval_token": "nsp_appr_..." }'
{
"data": {
"api_key_id": "ak_...",
"key_prefix": "nsp_test_4f2a1b3c",
"environment": "sandbox",
"scopes": ["catalog:read", "license:read", "..."],
"status": "active",
"secret": "nsp_test_xxxxxxxx"
}
}承認claimとブートストラップトークンは成功時にそれぞれ消費されます。2回目は401 invalid_approval_tokenを返します。紛失した場合はNUに再発行を依頼してください。ブートストラップキーには管理スコープがあり、より狭い統合キーを作成できます。api_keys:writeを持つサーバー側管理キーを少なくとも1つ維持し、Productionランタイムキーには通常キー管理スコープを付与しません。
APIキーのエンドポイント
| メソッドとパス | 必要な権限 | 用途 |
|---|---|---|
POST /v1/api-keys/bootstrap | 承認トークン | 公開 — 承認トークンから最初のSandboxキーを発行します。 |
GET /v1/api-keys | api_keys:read または api_keys:write | キーを一覧表示します。シークレットは返しません。 |
POST /v1/api-keys | api_keys:write | 別のキーを作成します。Productionにはproduction_api_enabled: trueのACTIVEなProduction dealが必要で、なければlicense_not_activeを返します。 |
PATCH /v1/api-keys/{id} | api_keys:write | scopes、allowed_origins、allowed_ipsを更新します。 |
POST /v1/api-keys/{id}/rotate | api_keys:write | 代替キーを発行し、旧キーを失効します。 |
DELETE /v1/api-keys/{id} | api_keys:write | キーを失効します。 |
SandboxとProductionのキー
| Sandbox | Production | |
|---|---|---|
| プレフィックス | nsp_test_ | nsp_live_ |
| ベースURL | https://signal-partners.newunivers.ai/v1 | https://signal-partners.newunivers.ai/v1 |
| データ | 分離されたダミーカタログ（isSandbox） | 実際のカタログ、deal、売上 |
| 再生 | ライセンス不要 | ACTIVEなライセンスdealが必要 |
| 精算 | 実際の金融精算書にアクセス不可 | 精算書の参照・異議申立て |
環境はキープレフィックス、カタログ表示、セッション、ログ、データで分離されます。nsp_test_はSandbox、nsp_live_はProductionを選びます。各リクエストはキーにエンコードされた環境で処理されます。
シークレットは一度だけ表示
完全なシークレットはキー作成時に一度だけ返されます。NUはハッシュのみ保存するため再表示できません。すぐにシークレットマネージャーへコピーし、紛失したら失効して新規作成します。
ステータス
| ステータス | 意味 |
|---|---|
ACTIVE | 使用可能です。 |
REVOKED | 手動で無効化済み。呼び出しは401 api_key_revokedを返します。 |
EXPIRED | 期限切れ。呼び出しは401 invalid_api_keyを返します。 |
ローテーション
POST /v1/api-keys/{id}/rotateは同じ環境、スコープ、制限の代替キーを発行し、1回の呼び出しで旧キーを失効します。無停止でローテーションするにはキーを重ねて使用します:
- 同じスコープで新しいキーを作成します。
- サーバーへ配布します。
X-NU-Request-Idで関連付け、トラフィックが新しいキーへ移行したことを確認します。- 旧キーを失効します。
定期的に、また漏えいが疑われたら直ちにローテーションしてください。失効するとキーはREVOKEDとなり以降の呼び出しは拒否されますが、既存の再生セッションやトークンは取り消されず、それぞれのTTLで失効します。
失効
失効は即時で取り消せません。以降そのキーによるすべての呼び出しは401 api_key_revokedを返します。
キーを使用できる場所を制限
| 制御 | 効果 |
|---|---|
allowed_origins | 再生トークンはこのリスト内のorigin値にだけ発行されます。 |
allowed_ips | 設定すると、リクエストは指定IPまたはCIDRから送信する必要があります。 |
scopes | キーが呼び出せるエンドポイントを制限します（認証）。 |
リリース前にallowed_originsとallowed_ipsを設定してください。これらはProductionチェックリストの一部です。allowed_origins外の再生originはトークン発行時に拒否されます。