認証

API自身の説明を返すインデックス以外のすべてのリクエストに、ヘッダーを1つ付けます。

Authorization: Bearer <your api key>

トークンはアカウントページで発行します。1アカウントにつき最大10個まで発行でき、個別に無効化できるため、漏洩したトークンだけを他に影響を与えずに削除できます。有料プランが必要です。有料プランがない場合、/と/v1/account以外のすべてのエンドポイントは403 plan_requiredを返します。

OAuth 2.1を使って、アプリケーションにトークンを取得させることもできます。ログインし、アプリケーションが求める権限を確認して「許可」を押すだけです。そのトークンも同じヘッダーで送信し、同じように機能します。

`?key=`を使わない理由

クエリ文字列に含めたキーは、意図しない場所に残ります。ウェブサーバーのアクセスログ、ブラウザの履歴、プロキシのログ、そしてレスポンスからリンクされた先に送られるRefererヘッダーなどです。そのためAPIはクエリ文字列のキーを受け付けず、その旨を401 missing_keyで返します。

ただし、メインサイトの旧?export=URLでは、引き続き?key=を受け付けます。何年も前に書かれたスクリプトがこれに依存しており、廃止すると動かなくなるためです。使えるのはこの1か所だけです。詳しくは旧エクスポートURLをご覧ください。

キーが有効か確認する

/v1/accountは最も負担の少ない呼び出しです。利用枠を消費せず、プランのないアカウントでも動作するため、「このキーは有効か」と「どこまで利用できるか」の両方を確認できます。

curl -H "Authorization: Bearer $KEY" https://api.publicwww.com/v1/account

{
  "plan": "enterprise",
  "plan_until": 1819461840,
  "full_access": true,
  "quota": {
    "searches": { "limit": 300, "used": 12, "resets_at": 1787961600 },
    "snippets": { "limit": 100, "used": 3,  "resets_at": 1787961600 }
  },
  "limits": {
    "disclosed_positions": 4294967295,
    "max_per_page": 1000000,
    "max_per_page_snippets": 10000
  }
}

起こりうるエラー

ステータス	コード	意味
401	`missing_key`	`Authorization: Bearer`ヘッダーがありません。クエリ文字列のキーは認められません。
401	`invalid_key`	キーに対応するアカウントがありません。余分な改行や引用符が含まれていないか確認してください。
403	`plan_required`	キーは有効ですが、アカウントに有料プランがありません。

401にはWWW-Authenticate: Bearerヘッダーも付くため、認証を汎用的に処理するHTTPクライアントも適切に動作します。

アプリケーション向けOAuth 2.1

アシスタント、連携ツール、ホスティング型サービスなど、他のユーザーの代わりに動作するアプリケーションは、ユーザー一人ひとりにトークンをコピーさせるべきではありません。代わりにユーザーをPublicWWWに案内します。ユーザーがログインしてアプリケーションを承認すると、アプリケーションは専用のトークンを受け取ります。このトークンは他のトークンと同様にAuthorization: Bearerとして送信し、そのアカウントのプラン、利用枠、レート制限の範囲内で、API全体とhttps://api.publicwww.com/mcpのMCPサーバーを利用できます。

項目	URL
認可サーバーのメタデータ（RFC 8414）	`https://publicwww.com/.well-known/oauth-authorization-server`
保護リソースのメタデータ（RFC 9728）	`https://api.publicwww.com/.well-known/oauth-protected-resource`
認可エンドポイント	`https://publicwww.com/oauth/authorize`
トークンエンドポイント	`https://publicwww.com/oauth/token`
取り消しエンドポイント（RFC 7009）	`https://publicwww.com/oauth/revoke`

アプリケーションの識別

クライアント登録はありません。client_idは、アプリケーションが公開する小さなJSONドキュメント（クライアントメタデータドキュメント）のhttps URLです。PublicWWWは誰かが連携するたびにこのドキュメントを読み込むため、名前やリダイレクト先は常に最新の状態に保たれ、承認するユーザーはどのホストがそれを公開しているかを確認できます。

{
  "client_id": "https://app.example.com/oauth/client.json",
  "client_name": "Example App",
  "redirect_uris": ["https://app.example.com/oauth/callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

ドキュメント内のclient_idは、そのドキュメントを配信しているURLと完全に一致する必要があります。ドキュメントはパスを含むURLからhttpsで、リダイレクトをたどらずに取得されます。5秒以内に応答し、64 KB未満である必要があります。
redirect_urisはhttpsのアドレスである必要があります。ユーザー自身のコンピューターで動作するアプリケーションの場合は、127.0.0.1、localhost、[::1]上のhttpも使えます。この場合、ポートは任意です。myapp://のようなカスタムスキームは受け付けません。
すべてのアプリケーションはパブリッククライアントとして扱われます。ドキュメントでtoken_endpoint_auth_methodに何を指定していても、トークンリクエストにシークレットは含めません。代わりに、認可コードはPKCEで保護されます。

フロー

PKCE付きの認可コードフローを使います。メソッドはS256のみです。ユーザーを認可エンドポイントに案内します。

https://publicwww.com/oauth/authorize
    ?response_type=code
    &client_id=https%3A%2F%2Fapp.example.com%2Foauth%2Fclient.json
    &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
    &code_challenge=<BASE64URL(SHA-256(code_verifier))>
    &code_challenge_method=S256
    &state=<random>

ユーザーは、まだログインしていなければメールで届くワンタイムコードでログインし、アプリケーションの名前、ドキュメントのホスト、戻り先を確認して、「許可」または「キャンセル」を押します。redirect_uriには、code、アプリケーションが送ったstate、iss=https://publicwww.com（RFC 9207）が返されます。認可コードの有効期間は10分で、使えるのは1回だけです。これをトークンと交換します。

curl https://publicwww.com/oauth/token \
     -d grant_type=authorization_code \
     -d code="$CODE" \
     -d code_verifier="$VERIFIER" \
     -d client_id=https://app.example.com/oauth/client.json \
     -d redirect_uri=https://app.example.com/oauth/callback

{ "access_token": "<token>", "token_type": "Bearer", "scope": "mcp" }

scopeは省略できます。スコープはmcpの1つだけで、API全体をカバーします。resource（RFC 8707）も省略できます。指定する場合はhttps://api.publicwww.com/mcpまたはhttps://api.publicwww.comです。

トークンの有効期間

取り消されるまで有効です。有効期限もリフレッシュトークンもありません。今日動いている連携は、誰も手を加えなくても明日も動き続けます。トークンが取り消されるのは、意図的な操作があった場合だけです。ユーザーがアカウントページでアプリケーションの連携を解除した場合、アプリケーション自身が取り消した場合、またはアカウントが削除された場合です。

curl https://publicwww.com/oauth/revoke \
     -d token="$TOKEN" \
     -d client_id=https://app.example.com/oauth/client.json

取り消しエンドポイントは、トークンが存在したかどうかにかかわらず、常に200を返します。

OAuthのエラー

発生箇所	コード	意味
認可	エラーページ	`client_id`のドキュメントを読み込めないか、`redirect_uri`がドキュメントに記載されていません。ユーザーはリダイレクトされません。検証されていないアドレスにリダイレクトすることはありません。
認可	`invalid_request`	`code_challenge`がないか、`S256`以外のメソッドが指定されています。
認可	`unsupported_response_type`	`response_type=code`以外が指定されています。
認可、トークン	`invalid_target`	API以外の`resource`が指定されています。
認可	`access_denied`	ユーザーが「キャンセル」を押しました。
トークン	`invalid_grant`	認可コードが不明、使用済み、期限切れ、または別の`client_id`に発行されたものです。あるいは`code_verifier`または`redirect_uri`が一致しません。
トークン	`unsupported_grant_type`	`authorization_code`以外が指定されています。

エラーページ以外の認可エラーは、error、error_description、state、issとしてredirect_uriに返されます。トークンのエラーは400で、同じ2つのフィールドをJSONで返します。

次へリクエストの送信

認証

?key=を使わない理由