認証
キーの形式、置き場所、キーごとの制限、ローテーション、そして漏えい時の対処。
API へのリクエストには、必ず Authorization ヘッダーで API キーを 1 つ付けます。
Authorization: Bearer sk-popnow-3f9c0a…これ以外の認証方法はありません。URL のクエリ文字列に入れたキーは受け付けず、popnow.ai のログイン状態も API では使えません。
例外が一つあります。/v1 配下の OpenAI 互換ルート は x-api-key ヘッダーからもキーを読み取るため、OpenAI 形式のクライアントをそのまま使えます。ネイティブの /api/v1 ルートが読むのは Authorization だけです。
キーの形式
キーは sk-popnow- に小文字の 16 進数 48 文字が続く形式です。作成後の API コンソールには先頭の数文字しか表示されないため、なくしたキーは復元できません。新しく作成してください。
キーを作成する
- popnow.ai にログインし、API コンソールを開きます。
- Create key を選び、
production-backendのように使い道がわかる名前を付けます。 - すぐにコピーします。全体が表示されるのはこの一度だけです。
キーは同時に複数持てます。環境ごと・サービスごとに分けておくと、1 つだけを無効化しても他に影響しません。どのキーも同じクレジット残高から支払います。
キーの置き場所
- 環境変数やプラットフォームのシークレット管理（
POPNOW_API_KEY）に置き、ソースコードには書きません。 - ブラウザやモバイルアプリなど、他人の端末で動くコードには絶対に入れないでください。キーを読める人は誰でもあなたのクレジットを使えます。自分のサーバーを間に置き、そこから PopNow を呼び出します。
- ログにも残さないでください。リクエストヘッダーを記録するなら、先に
Authorizationを取り除きます。
キーにできることを制限する
キーごとに、API コンソールで個別の制限を設定できます。
| 制限 | 内容 | ブロック時のエラー |
|---|---|---|
| 許可するモデル | 指定したモデルだけを呼び出せる | 40301 |
| IP 許可リスト | 指定したアドレスや範囲からのリクエストだけを受け付ける | 40302 |
| 利用上限 | このキーの日・月・累計の上限（クレジット表示） | 40202 |
初期状態のキーには制限も上限もありません。本番用のキーには、動作に必要な最小限だけを許可しましょう。
タスクは作成したキーに属する
recordInfo、retry、purge、タスク一覧、利用状況から見えるのは、同じキーで作ったタスクだけです。同じアカウントの別のキーで作ったタスクは、存在しないタスクと同じく 404 になります。Web サイトで始めた生成も、どのキーからも見えません。アカウント全体を見るには API コンソールを使ってください。
ローテーション
停止時間なしでキーを入れ替える手順:
- 新しいキーを作成する。
- 古いキーを使っていたすべての場所に配備する。
- コンソールで古いキーの最終使用時刻が動かなくなったことを確認する。
- 古いキーを無効化する。
キーが漏れたら
- すぐに無効化する。 API コンソールで操作すると、次のリクエストから効きます。
- 代わりのキーを作って配備する。
- 何に使われたか確認する。 コンソールのログと利用状況に、そのキーが作ったタスクがすべて残っています。
- 新しいキーを絞り込む。 IP 許可リストと利用上限を設定します。
身に覚えのない利用があればサポートに連絡してください。
失敗時の応答
認証の問題は 3 種類とも HTTP 401、code: 401 を返し、msg で区別します。
msg の内容 | 何が起きたか | 対処 |
|---|---|---|
| 認証情報がない | Authorization ヘッダーが届いていない | ヘッダーが設定されているか、実行中のプロセスに環境変数が読み込まれているかを確認 |
| キーの形式が認識できない | 値は届いたが PopNow のキーではない | sk-popnow- で始まるか確認。別の値を貼り付けた可能性があります |
| 認証情報が無効または期限切れ | キーが存在しない、無効化済み、または期限切れ | 新しいキーを作成。再試行しても成功しません |
有効なキーでも 403 で拒否されることがあります。たとえばアカウントのメールアドレスが未確認の場合（40310）です。エラーを参照してください。