認証と API キー
キーの送信方法
正規のヘッダーは X-API-Key です：
curl -X POST 'https://api.cognivolabs.io/v1/api/intel/risk' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"chain":"eth","address":"0xTOKEN_CONTRACT"}'
Authorization: Bearer YOUR_API_KEY も、それを好むクライアントライブラリ向けのエイリアスとして受け付けられます。
キーの保存方法
Cognivo が完全なキーを保存することはありません。保持されるのは一方向ハッシュとプレフィックス、末尾 4 文字だけです。だからこそ完全なキーは作成時に一度だけ表示できます。パスワードと同じように扱ってください。
サンドボックスキーとライブキー
| プレフィックス | 用途 | 課金 | レート上限 |
|---|---|---|---|
cogv_test_ | サンドボックス：限定的なデモとインテグレーションテスト専用。Sandbox と明確にラベル付けされ、ライブインテリジェンスは実行できません | 課金なし | 25 リクエスト/時、100/日、1/秒のハード上限 |
cogv_live_ | 本番。セルフサービスですぐに動きます | 従量課金：成功した呼び出しごとにクレジット残高から Cognivo クレジットを消費。失敗した呼び出しには課金されません | あなたのアクセスモード制限。開始時は 1,000 リクエスト/時 |
必要ならサンドボックスキーでリクエストの形をプロトタイピングし、その後ライブキーでリリースしてください。新しいライブキーに承認もトライアルも不要です。アカウントにクレジットがあるかぎり、作成した瞬間から動き始めます。
アクセスモードをわかりやすく
- ライブ（標準） - セルフサービスの従量課金。新しいライブキーはすぐに動き、成功した呼び出しごとに公開されているエンドポイント別価格で Cognivo クレジットが課金されます。残高が呼び出しをカバーできない場合は
402 payment_requiredが返り（課金なし）、Cognivo アカウントの課金ページでチャージして再試行してください。 - サンドボックス -
cogv_test_キー。限定的なデモ/テスト専用で、ライブインテリジェンスは実行できません。ライブ呼び出しには403 sandbox_limitedが返ります。 - トライアル - 管理者が付与する任意の評価枠（制限付きかつ期限付き）。通常の有料利用には不要です。
- パートナー - 管理者が管理するアレンジメントです。
- エンタープライズ - アクセスをリクエストする経路：カスタム料金、カスタム上限、大量利用。Developer ポータルからリクエストしてください。
- 停止（suspended） - キーは何も実行できません。理由はポータルに表示されます。
- レガシーのメタデータ専用キー - セルフサービス課金より前に作られた少数の古いキーは、メタデータエンドポイントしか呼び出せません。ライブ呼び出しには
403 access_requiredが返ります。従量課金に移行するには、新しいライブキーを作成してください。
GET /v1/api/me は、キーがどのモードにあるか（access_mode）に加えて、アカウントの credits_balance と top_up ガイダンスを教えてくれます。
スコープ（権限）
キーはデフォルト拒否です。キーは作成時に付与したエンドポイントグループしか呼び出せません。スコープは 3 つあり、それぞれがエンドポイントのセットを解放するだけのシンプルな仕組みです。
intel:read - トークンとウォレットのインテリジェンス
日常使いのスコープです。「このトークンやウォレットで何が起きているのか？」をキーに問い合わせられます：価格下落の要因、リスクシグナル、チームウォレットの挙動、実現損益、正確な資金移動。
解放されるもの：POST /v1/api/intel/why-down、POST /v1/api/intel/team-wallets、POST /v1/api/intel/risk、POST /v1/api/wallet/pnl、POST /v1/api/wallet/exact-movements
security:read - ウォレット安全性スキャン
ウォレットが何を承認しているかをチェックできます：どのコントラクトがそのトークンを使用できるかを調べ、無制限の許可（allowance）にフラグを立てます。読み取り専用です。このスコープを持つキーが資金を動かしたり、何かを取り消したりすることは決してできません。
解放されるもの：POST /v1/api/wallet/approvals
liquidity:read - 流動性と LP の読み取り
トークンの流動性が本物かどうか、LP トークンがどこにあるかをチェックできます：プールの状況、LP のカストディ、ロックとバーンの状況。
解放されるもの：POST /v1/api/intel/liquidity
GET /v1/api/health はキーが一切不要です。GET /v1/api/me と GET /v1/api/discover は、スコープに関係なくあらゆる有効なキーで動作します。
キーのスコープはポータルでいつでも編集できます。呼び出しが 403 scope_denied で失敗する場合、そのキーがそのエンドポイントに必要なスコープを持っていないだけです。
ローテーションと失効
- 失効（Revoke） はキーを無効化します。1 分以内に認証できなくなります。
- ローテーション（Rotate） は同じ名前・スコープ・ティアの代替キーを作成し、一度だけ表示して、同じステップで古いキーを失効させます。漏洩が疑われるときと、定期的なスケジュールで使ってください。
任意の制限
キーごとに、追加で許可リストを設定できます：
- オリジン（完全一致のオリジン、または
https://*.yourapp.comのようなワイルドカードサブドメイン） - 異なるOriginを提示するリクエストは拒否されます。 - IP / CIDR 範囲 - それ以外のアドレスからのリクエストは拒否されます。
リストが空の場合は制限なしを意味します。
キーの発行元
キーは、既存の Cognivo アカウントを使って、セルフサービスの Developer ポータルでのみ作成されます。新規インテグレーション向けの手動/レガシーなキー発行はありません。