Agentic Registration: How an AI Agent Signs Up for Bright Data With auth.md

TL;DR

AIエージェントは、人間がサインアップフォームに入力することなく、Bright Dataのアカウントを作成し、有効なAPIトークンを受け取ることができます。このプロトコルはhttps://brightdata.com/auth.mdに存在し、ディスカバリーメタデータのagent_authブロック内で告知されています。

3回の呼び出しで完了します:

1. ユーザーのメールアドレスを添えてPOST /users/auth/agent_registration/authを呼び出します。claim_tokenが返されます。この時点ではまだ認証情報はありません。
2. ユーザーは受信トレイから6文字のコードを読み取り、エージェントに渡します。
3. claim_tokenとコードを添えてPOST /users/auth/agent_registration/claim/completeを呼び出します。APIトークンが返されます。

アカウントは月間5,000の無料クレジット、7日間有効な2ドルのトライアルクレジット、そして事前作成された3つのゾーン(agent_serp、agent_unlocker、agent_browser_api)から始まります。どのゾーンへの最初の呼び出しも、セットアップ不要ですぐに動作します。

課題

すべてのサインアップフォームは人間が操作することを前提としています。プランを選択し、確認リンクをクリックし、ダッシュボードを開き、設定を見つけ、キーをコピーし、どこかに貼り付ける。

キーを必要とするのがエージェントの場合、この仕組みは破綻します。40の小売業者から価格情報を取得するよう依頼されたコーディングエージェントは、スクレイパーを作成し、リトライを処理し、出力をパースすることができます。しかし、自分が持っていないブラウザ上でボタンをクリックすることはできません。

そのため、最初のステップで止まってしまいます。そしてこの停止は見た目以上に厄介です。なぜなら、障害は能力の問題ではないからです。

エージェントは、できるとしても許可されていない

明らかな反論として、ブラウザ自動化がこれを解決するというものがあります。エージェントにChrome拡張機能やPlaywrightセッションを与えれば、他の誰かと同じようにサインアップフォームに入力できるはずだという考えです。

できるのは事実です。しかし、許可されていません。

Anthropicのブラウザエージェントは、ユーザーに代わってアカウントを作成することを禁じられています。これは単なる推奨事項でも、許可を求めるプロンプトでもありません。アカウント作成は、銀行データの取り扱いや完全な削除の実行と並んで禁止リストに含まれており、ユーザーが明示的に依頼し許可を与えた場合でも拒否されることを意味します。指示内容は、ユーザー自身にアカウント作成を行わせるよう誘導することです。

さらに2つのルールにより、サインアップフォームはそれだけでもほぼ使用不可能になります。Claudeはボット検出や人間確認システムを尊重し、ユーザーに代わってそれらを完了させることはありません。また、Anthropicの公開済み安全性文書によると、規約や条件、合意への同意には毎回明示的なユーザー承認が必要です。標準的なサインアップフォームは、エージェントに対してアカウント作成、CAPTCHAの解決、利用規約への同意という3つを一度に求めてきます。

これは妥当な線引きです。任意のメールアドレスに対して黙ってアカウントを登録できるエージェントは、不正利用エンジンに他なりません。この制限には正当な理由があり、緩和される見込みはありません。

データプロバイダーにとって、この結果は具体的な意味を持ちます。サインアップフォームはエージェントにとって遅い経路ではありません。閉ざされた経路です。エージェントにブラウザを与えても解決にはなりません。なぜなら、ブラウザは元々障害ではなかったからです。

auth.mdは、ポリシーが必要とする場所に同意を配置します。このフローでは、エージェントが人間になりすますことを決して求めません。エージェントはHTTP呼び出しを行います。人間は自分自身の受信トレイからワンタイムコードを取得し、それを渡します。アカウントはユーザーの積極的な参加なしには作成できないため、ユーザーがそれを知らないままになることはありません。エージェントは代理人ではなく、クライアントなのです。

これが、OTPステップが工学的に排除されるのではなく、プロトコルに組み込まれている理由です。これは人間向けサインアップフローの残存する摩擦ではありません。これは同意のメカニズムであり、これこそがエージェントが単に完了できるだけでなく、完了することを許可される要因となっています。

エージェントがこれをどう見つけるか

Bright Dataを見たことがないエージェントでも、標準メタデータからこのフローにたどり着けます。

GET https://brightdata.com/.well-known/oauth-authorization-server

レスポンスにはagent_authブロックが含まれています:

{
  "agent_auth": {
    "skill": "https://brightdata.com/auth.md",
    "register_uri": "https://brightdata.com/users/auth/agent_registration/auth",
    "claim_uri": "https://brightdata.com/users/auth/agent_registration/claim",
    "identity_types_supported": ["identity_assertion"],
    "identity_assertion": {
      "assertion_types_supported": ["verified_email"],
      "credential_types_supported": ["api_key"]
    }
  }
}

このブロックが契約内容です。github_tokenとanonymousは、リリースされ次第ここに表示されます。メタデータに記載されているメソッドのみを使用し、古いバージョンの文書から記憶しているメソッドは使用しないでください。

APIについては保護リソースメタデータもあります:

GET https://api.brightdata.com/.well-known/oauth-protected-resource

{
  "resource": "https://api.brightdata.com/",
  "resource_name": "Bright Data API",
  "authorization_servers": ["https://brightdata.com"],
  "scopes_supported": ["serp", "unlocker", "wsapi", "scraper_studio",
      "discover", "browser", "usage:read"],
  "bearer_methods_supported": ["header"]
}

エンドポイントはランタイムで自己文書化されます。GET https://brightdata.com/users/auth/agent_registrationは、エンドポイント契約とエラーテーブルの機械可読なマークダウンコピーを返します。このレスポンスとauth.mdが食い違う場合、エンドポイントのレスポンスがリアルタイムの正とされます。これは独立してオフにすることも可能で、その場合は404とともにinstructions_disabledが返され、エージェントはauth.mdにフォールバックします。

4つの登録方法

プログラムによる登録は完全自動化された経路です。しかし唯一の方法ではありません。

このガイドの残りの部分では最初の方法について説明します。

ステップ1: 発見

認可サーバーのメタデータを読み取り、どのアサーションタイプが有効かを確認します。現時点ではverified_emailのみです。

curl https://brightdata.com/.well-known/oauth-authorization-server

ステップ2: 登録

ユーザーの実際の受信メールアドレスを使用してください。使い捨てドメインや[email protected]のようなプラスエイリアス付きアドレスは拒否されます。

curl -X POST https://brightdata.com/users/auth/agent_registration/auth \
  -H "Content-Type: application/json" \
  -d '{
    "type": "identity_assertion",
    "assertion_type": "verified_email",
    "assertion": "[email protected]",
    "client": "claude-code"
  }'

clientは任意ですが、指定することを推奨します。最大100文字のエージェント名を宣言することで、サポートや診断に役立つ情報を提供できます。

レスポンスには認証情報は含まれません:

{
  "claim_token": "<uuid-v4>",
  "state": "pending",
  "otp_expires_at": "<ISO 8601 timestamp>",
  "claim_token_expires_at": "<ISO 8601, 24 hours from registration by default>"
}

claim_tokenはUUID v4であり、登録自体の識別子です。別途registration_idはありません。これをメモリに保持し、そのままステップ3に渡してください。

ユーザーの個人情報を送信する前に、サービス名であるBright Dataと、そのアカウントでできることをユーザーに示してください。これらのエンドポイントを呼び出すことは、提供されたメールアドレスに代わってBright Dataの利用規約および許容可能な使用ポリシーへの同意を主張することになります。

ステップ3: 確認

Bright Dataはユーザーに、デフォルトで10分間有効な6文字の英数字混合ケースのコードをメールで送信します。ユーザーにそのコードを読み上げてもらいます。

curl -X POST https://brightdata.com/users/auth/agent_registration/claim/complete \
  -H "Content-Type: application/json" \
  -d '{
    "claim_token": "<uuid-v4>",
    "otp": "aB3xY9"
  }'

ここで認証情報が発行されます:

{
  "claim_token": "<uuid-v4>",
  "credential": { "token": "<api_token>", "id": "<token_id>" },
  "zones": {
    "serp":        { "zone_id": "agent_serp",        "status": "success" },
    "unlocker":    { "zone_id": "agent_unlocker",    "status": "success" },
    "browser_api": { "zone_id": "agent_browser_api", "status": "success" }
  }
}

コードを再送するには、claim_tokenを/users/auth/agent_registration/claimにPOSTしてください。これにより以前のコードは無効になりますが、残りの試行回数はリセットされず、登録ごとに再送は3回まで、最小間隔は60秒に制限されています。

アカウントはこれで、無料枠と2ドルのトライアルクレジットとともに有効になります。確認されないまま保留中の登録は24時間後に期限切れとなります。

ステップ4: 認証情報を使用する

SERPゾーンを通じたウェブ検索:

curl -X POST https://api.brightdata.com/request \
  -H "Authorization: Bearer <api_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "zone": "agent_serp",
    "url": "https://www.google.com/search?q=web+scraping+tools",
    "format": "json"
  }'

Web Unlockerを通じて保護されたページをスクレイピング:

curl -X POST https://api.brightdata.com/request \
  -H "Authorization: Bearer <api_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "zone": "agent_unlocker",
    "url": "https://example.com",
    "format": "raw"
  }'

ブラウザAPIについては、PlaywrightやPuppeteer、SeleniumをCDP経由でagent_browser_apiゾーンに接続してください。これは2ドルのトライアルクレジットを使用します。セットアップ方法はhttps://docs.brightdata.com/scraping-automation/scraping-browser/quickstartにあります。

完全なMCPツールセットについては、https://mcp.brightdata.com/mcp?token=<api_token>を使用してください。

Web Scraper APIsはゾーンベースではなく、登録によって自動プロビジョニングされることもありません。これらはhttps://docs.brightdata.com/datasets/introductionに文書化された、別途のトリガー、ポーリング、ダウンロードの仕組みで動作します。

アカウントが得られるもの

含まれないもの: プロキシネットワーク、アカウント管理、ゾーンの作成や編集。レジデンシャルプロキシは常にコントロールパネルを通じたKYC確認済みのビジネスアカウントを必要とします。人間はいつでもそこで資金を追加し、制限を解除できます。

トークンの権限プロファイルは意図的に最小限に抑えられています。管理と請求に対しては読み取り専用であり、ゾーンの作成や編集はできません。これが、必要な3つのゾーンが事前にプロビジョニングされている理由です。

素朴な実装を壊す7つの挙動

このフローを汎用のサインアップフォームとして扱うと、エージェントが誤りを起こす部分です。

ステップ2での200レスポンスは、メールアドレスが新規であることの証明にはなりません。そのアドレスが既にBright Dataアカウントに属している場合、または管理されたロールアウト中にドメインやメールの許可リストによってフィルタリングされた場合、レスポンスの形式は成功時と同一であり、コードは送信されません。既存アカウントの所有者には代わりに別の通知メールが送られます。これは意図的な仕様であり、成功とは区別できません。ユーザーがコードを受け取っていないと報告した場合は、繰り返しリトライさせるのではなく、迷惑メールフォルダを確認し、既にアカウントを持っていないか確認するよう依頼してください。

ステップ2を繰り返しても何もリスタートされません。登録が保留中の同じメールアドレスに対して/authを再度呼び出すと、同じclaim_tokenと変更されていない有効期限のタイムスタンプが返されます。新しいコードを得るには再送エンドポイントを使用してください。

ゾーンのプロビジョニングは製品ごとに独立しており、個別に失敗する可能性があります。zones配下の全エントリを確認してください。他が成功している中で1つの製品が"status": "failed"を報告している場合、それはその製品だけを後でリトライすべきということであり、登録全体が失敗したわけではありません。

/claim/completeは冪等です。タイムアウトやネットワークエラーの後に同じclaim_tokenとコードでリトライしても、同一の結果が返されます。2つ目のアカウントが作成されたり、2つ目の認証情報が発行されたり、権限が二重に付与されることはありません。安全にリトライできます。

認証情報は秘密情報です。credential.tokenをチャットの出力、トランスクリプト、コマンドライン引数、あるいは意図しない第三者が読める可能性のあるファイルに決して出力、ログ記録、エコーしないでください。シークレットマネージャー、OSの認証情報ストア、またはバージョン管理から除外し制限的な権限を持つ.envファイルに保存してください。プレーンテキストのソースコード、シェル履歴、ログには保存しないでください。

レート制限は5つの次元にわたって適用されます。デフォルト値: メールアドレスごとに1時間あたり3回の登録開始、送信元IPごとに1時間あたり60回、ネットワーク範囲ごとに1時間あたり30回、メールドメインごとに1時間あたり50回、グローバルで1時間あたり1,000回。いずれかを超過するとrate_limitedが返されます。登録は不正検出スクリーニングも通過します。

有効だったはずの認証情報で401が返された場合は、ディスカバリーを再開してください。認証情報を破棄し、ステップ1に戻ってください。呼び出しをそのままリトライしないでください。

エラーコード

/auth、/claim、/claim/completeからの2xx以外のレスポンスはすべて同じ形式を使用します: {"error": "<code>", "error_description": "<actionable next step>"}。この説明文は散文ではなく、次に取るべき行動です。内部の不正検出しきい値、スコア、ベンダー名が含まれることは決してありません。

5xxは指数バックオフでリトライしてください。テーブルに指示がない限り、同じ4xxペイロードをリトライしないでください。

失効

エージェントは失効を開始できません。エージェントが認証情報を返却するためのエンドポイントは存在しません。

認証情報が機能しなくなり、APIが401を返した場合は、それを破棄してステップ1からディスカバリーを再開してください。これが契約の全てです。無効なトークンを保持しているエージェントは、それをリトライしてはならず、リフレッシュを試みてもならず、アカウントが削除されたと想定してもなりません。メタデータに戻り、改めて開始すべきです。

後からアカウントを引き継ぐ

人間は後から、パスワード、GitHub、またはGoogleを使った標準的なサインアップを同じメールアドレスで完了させ、その同じアカウントへの完全なアクセス権を得ることができます。これにより重複は作成されず、エージェントが既に使用している認証情報も無効化されません。そのアドレスでのパスワードリセットが、ゼロからコントロールパネルに入る方法です。

まだリリースされていない機能

エージェントがこれを試みてリクエストを無駄にしないよう、明示的に述べておきます。

GitHubトークンによるアサーションは計画中ですが、スケジュールは未定です。設計では、認証済みのGitHub CLIからトークンを読み取り、GitHubサーバー側でそれを検証し、確認済みのプライマリメールアドレスを読み取り、GitHubの数値IDでアカウントをキー化します。トークンは一度だけ使用され、保存されることはありません。アイデンティティが既に検証済みであるため、コードのステップなしで認証情報が即座に返されます。最小限のスコープはread:userとuser:emailになる見込みで、確認済みのプライマリメールアドレスを持たないGitHubアカウントは拒否されます。

これらはいずれも実装されていません。サーバーはverified_emailのみを受け付け、それ以外はすべてinvalid_requestとして拒否します。invalid_github_tokenとemail_unverifiedのコードは予約済みであり、現時点では返されません。

匿名登録は計画中ですが、スケジュールは未定です。

両方に共通するルールです: メタデータからassertion_types_supportedを読み取り、そこに記載されているものだけを使用してください。これらがリリースされた際、まずメタデータに表示されます。

リファレンス

プロトコル内のすべてのURL:

CLI: npm install -g @brightdata/cli

SDK: npm install @brightdata/sdkまたはpip install brightdata-sdk

よくある質問

AIエージェントは人間なしでBright Dataのアカウントを作成できますか?

ほぼ完全に可能です。エージェントがすべてのHTTP呼び出しを行います。人間が行う唯一の操作は、メールから6文字のコードを読み取り、それをエージェントに渡すことだけです。フォームもダッシュボードもブラウザも不要です。

なぜエージェントはブラウザツールで通常のサインアップフォームに入力するだけではだめなのですか?

許可されていないからです。Anthropicは、ユーザーの明示的な許可があっても、ブラウザエージェントがユーザーに代わってアカウントを作成することを禁止しており、別途CAPTCHAや人間確認を完了させないよう指示しています。サインアップフォームはその両方を要求します。auth.mdのフローは、エージェントに人間として振る舞うことを決して求めないことでこれを回避しています。

このプロトコルはどこに文書化されていますか?

https://brightdata.com/auth.md、そしてhttps://brightdata.com/users/auth/agent_registrationに機械可読な形式でミラーされています。

エージェントはどうやってエンドポイントを発見しますか?

https://brightdata.com/.well-known/oauth-authorization-server内のagent_authブロックからです。

エージェントは何を得られますか?

標準的なBright Data APIトークン、月間5,000の無料クレジット、7日間有効な2ドルのトライアルクレジット、そしてSERP、Web Unlocker、Browser API用に事前プロビジョニングされた3つのゾーンです。

トークンには有効期限がありますか?

デフォルトでおおよそ1年程度です。正確な有効期限は登録レスポンスには含まれていません。

エージェントは独自のゾーンを作成できますか?

いいえ。トークンは管理と請求に対して読み取り専用です。必要な3つのゾーンは事前にプロビジョニングされています。

エージェントは自身の認証情報を失効させることができますか?

いいえ。エージェントは失効を開始できません。認証情報が401を返した場合は、それを破棄してディスカバリーを再開してください。

エージェントはレジデンシャルプロキシを使用できますか?

いいえ。それらは常にコントロールパネルを通じたKYC確認済みのビジネスアカウントを必要とします。

これはID-JAGですか?

いいえ。これはBright Data独自のエージェント登録フローです。

試してみる

エージェントにhttps://brightdata.com/auth.mdを指し示し、登録するよう依頼してください。3回の呼び出しの後には、トークン、3つの動作可能なゾーン、そして月間5,000の無料クレジットが手に入ります。