简要说明
AI 智能体无需人工填写注册表单,即可创建 Bright Data 账户并获得可用的 API 令牌。该协议位于 https://brightdata.com/auth.md并在发现元数据的 agent_auth 块中公布。
只需三次调用:
- 使用用户的电子邮箱调用
POST /users/auth/agent_registration/auth。返回一个claim_token。此时还没有凭证。 - 用户从收件箱中读取一个 6 字符代码并将其提供给智能体。
- 使用
claim_token和该代码调用POST /users/auth/agent_registration/claim/complete。返回 API 令牌。
账户初始每月可获得 5,000 个免费积分、有效期为 7 天的 2 美元试用额度,以及三个预先创建的区域:agent_serp、agent_unlocker、agent_browser_api。无需任何设置,首次调用其中任意区域即可使用。

问题
所有注册表单都默认操作者是人类。选择套餐、点击验证链接、打开控制面板、找到设置、复制密钥,再将其粘贴到某处。
当需要密钥的是智能体时,这套流程就行不通了。一个被要求从 40 家零售商获取价格的编程智能体可以编写爬虫、处理重试并解析输出,但它无法在自己并不具备的浏览器中点击按钮。
因此,它在第零步就停住了。而这种阻碍比表面上更棘手,因为问题并非能力不足。
即使智能体有能力,也不允许这样做
显而易见的反对意见是,浏览器自动化可以解决这个问题。给智能体一个 Chrome 扩展程序或 Playwright 会话,它就能像其他人一样填写注册表单。
它确实能做到,但不被允许这样做。
Anthropic 禁止其浏览器智能体代用户创建账户。这不是一种软性偏好,也不是权限确认提示。账户创建与处理银行数据和执行永久删除一样,都被列入禁止事项,这意味着即使用户明确提出要求并授予权限,智能体也会拒绝。相关指示要求智能体让用户自行创建账户。
即使没有这条规定,另外两项规则也会让注册表单几乎无法使用。Claude 会尊重机器人检测和人工验证系统,不会代用户完成这些验证。此外,根据 Anthropic 已发布的安全文档每次接受条款、条件或协议时都需要用户明确批准。标准注册表单要求智能体同时完成三件事:创建账户、通过 CAPTCHA,以及接受服务条款。
这是一条合理的界线。能够使用任意电子邮箱地址静默注册账户的智能体会成为滥用工具。这项限制有充分理由,而且不会被放宽。
这对数据提供商而言会带来明确后果。对智能体来说,注册表单不是一条较慢的路径,而是一条封闭的路径。为智能体提供浏览器也无济于事,因为浏览器从来都不是阻碍所在。
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 返回一份机器可读的 Markdown,其中包含端点约定和错误表。如果该响应与 auth.md 不一致,应以端点响应为当前有效依据。此功能可以单独关闭;关闭后,它会返回包含 404 的 instructions_disabled智能体则回退到 auth.md。
四种接入方式
程序化注册是完全自动化的路径,但并非唯一选择。
| 路径 | 人工需要执行的操作 | 适用场景 |
|---|---|---|
| 电子邮箱注册 | 从收件箱中读取一个代码 | 智能体需要自己的凭证,且不存在浏览器会话 |
| API 令牌 | 粘贴一次令牌 | 用户已有账户。令牌可从 https://brightdata.com/cp/setting/users 获取 |
| 通过 OAuth 使用托管 MCP | 在浏览器中完成 OAuth | 有可用浏览器。连接到 https://mcp.brightdata.com/mcp |
| CLI 登录 | 通过浏览器或设备流程完成点击操作 | 终端环境。使用 npx @brightdata/cli login;如果 GitHub CLI 已完成身份验证,则使用 brightdata login --github |
本指南的其余部分将介绍第一种方式。
第 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 会向用户发送一个由字母和数字组成、区分大小写的 6 字符代码,默认有效期为 10 分钟。请用户读出该代码。
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。这会使之前的代码失效,但不会重置剩余尝试次数。每次注册最多可重发 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"
}'
通过网络解锁器抓取受保护页面:
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"
}'
如需使用 Browser API,请通过 CDP 将 Playwright、Puppeteer 或 Selenium 连接到 agent_browser_api 区域。这会消耗 2 美元试用额度。设置说明位于 https://docs.brightdata.com/scraping-automation/scraping-browser/quickstart。
如需使用完整的 MCP 工具集,请使用 https://mcp.brightdata.com/mcp?token=<api_token>。
Web 爬虫工具 API 并非基于区域,也不会在注册时自动配置。它们通过单独的触发、轮询和下载机制运行,相关文档位于 https://docs.brightdata.com/datasets/introduction。
账户可获得的内容
| 项目 | 详情 |
|---|---|
| 免费积分 | 每月 5,000 个,按月续发。可用于网络解锁器、SERP、网页爬虫工具 API 和抓取工具 Studio |
| 试用额度 | 一次性 2 美元,有效期 7 天,适用于包括 Browser API 在内的任何产品。添加付款方式后,可再获得 5 美元,并将试用期延长至 30 天 |
| 区域 | 预先创建的 agent_serp、agent_unlocker、agent_browser_api |
| 用量和账单 | 只读。可以查看余额,但无法访问付款方式或发票 |
| 令牌有效期 | 默认大约一年。不返回确切的到期时间 |
不包括:代理网络、账户管理,以及创建或编辑区域。住宅代理始终需要通过控制面板使用已完成 KYC 验证的企业账户。用户可以随时在控制面板中充值并解除限制。
令牌的权限配置经过刻意精简。它对管理和账单仅有只读权限,无法创建或编辑区域,因此所需的三个区域会被预先配置。
会导致简单实现出错的七种行为
如果智能体将该流程当作普通注册表单处理,通常会在以下方面出错。
第 2 步返回 200 并不能证明该电子邮箱是新用户。如果该地址已属于某个 Bright Data 账户,或在受控发布期间被域名或电子邮箱白名单过滤,响应结构会与成功时完全相同,但不会发送代码。现有账户的所有者会另外收到一封通知邮件。这是有意设计的行为,无法与成功响应区分。如果用户表示始终没有收到代码,请让其检查垃圾邮件,并确认自己是否已拥有账户,而不是循环重试。
重复第 2 步不会重新启动任何流程。当同一电子邮箱有待处理的注册时,再次调用 /auth 会返回相同的 claim_token到期时间戳也保持不变。如需新代码,请使用重发端点。
区域配置按产品分别进行,且可能独立失败。检查 zones 下的每个条目。如果一个产品报告 "status": "failed"而其他产品均成功,这意味着稍后应重试该产品,并不表示整个注册失败。
/claim/complete 具有幂等性。在超时或网络错误后,使用相同的 claim_token 和代码重试会返回完全相同的结果。它不会创建第二个账户、签发第二份凭证,也不会重复授予权益。可以安全重试。
凭证属于机密信息。切勿将 credential.token 打印、记录或回显到聊天输出、对话记录、命令行参数,或任何可能被无关人员读取的文件中。应将其存储在密钥管理器、操作系统凭证存储区,或已从版本控制中排除且权限受限的 .env 文件中。不要存放在明文源代码、Shell 历史记录或日志中。
速率限制涵盖五个维度。默认值:每个电子邮箱每小时最多发起 3 次注册、每个源 IP 每小时 60 次、每个网段每小时 30 次、每个电子邮箱域名每小时 50 次,以及全局每小时 1,000 次。超过任意一项都会返回 rate_limited。注册还会经过欺诈筛查。
有效凭证返回 401 表示需要重新执行发现流程。丢弃该凭证并返回第 1 步。不要重试该调用。
错误代码
来自 /auth、/claim 和 /claim/complete 的每个非 2xx 响应都采用相同结构:{"error": "<code>", "error_description": "<actionable next step>"}。描述字段用于说明下一步操作,而不是一般性文字。响应绝不会包含内部欺诈阈值、评分或供应商名称。
| 代码 | HTTP | 出现位置 | 处理方式 |
|---|---|---|---|
invalid_request |
400 | 全部三个端点 | 修正 JSON 请求体 |
email_not_accepted |
400 | /auth |
一次性、带别名或无效的地址。请用户提供真实邮箱 |
registration_denied |
403 | /auth、/claim/complete |
已拒绝。不要重试。改用有人类参与的备用路径 |
browser_signup_required |
403 | /auth |
此电子邮箱必须在浏览器中注册。不要重试。让用户使用相同地址在控制面板注册 |
fraud_check_unavailable |
503 | /auth |
可以重试。至少等待 Retry-After 秒后重试完全相同的请求;每次失败后将等待时间加倍,总共尝试 3 次,然后回退到人工路径 |
rate_limited |
429 | 任意端点 | 退避并稍后重试 |
invalid_claim_token |
400 | /claim、/claim/complete |
无效、未知或次数已用尽(5 次 OTP 尝试或 3 次重发)。重新开始注册 |
otp_invalid |
400 | /claim/complete |
让用户重新确认代码。连续输错 5 次后,该认领将永久失效 |
otp_expired |
400 | /claim/complete |
通过 /claim 重新发送。代码默认有效期为 10 分钟 |
claim_expired |
400 | /claim/complete |
待处理注册已超过 24 小时。重新开始 |
registration_disabled |
503 | /auth |
新注册暂时关闭。使用备用路径 |
instructions_disabled |
404 | GET 发现端点 | 自文档端点已关闭。以 auth.md 为准 |
invalid_github_token |
401 | /auth |
保留代码。目前不会返回 |
email_unverified |
401 | /auth |
保留代码。目前不会返回 |
对 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:
| URL | 用途 |
|---|---|
https://brightdata.com/auth.md |
协议文档。规范版本 |
https://brightdata.com/.well-known/oauth-authorization-server |
包含 agent_auth 块的授权服务器元数据 |
https://api.brightdata.com/.well-known/oauth-protected-resource |
受保护资源的元数据、权限范围和不记名令牌方法 |
https://brightdata.com/users/auth/agent_registration |
实时、自文档化的约定和错误镜像 |
.../agent_registration/auth |
开始注册 |
.../agent_registration/claim |
重新发送代码 |
.../agent_registration/claim/complete |
提交代码并接收令牌 |
https://api.brightdata.com/request |
SERP 和网络解锁器调用 |
https://mcp.brightdata.com/mcp |
托管 MCP,完整工具集 |
https://brightdata.com/cp/setting/users |
供用户查找现有 API 令牌的位置 |
https://docs.brightdata.com |
API 参考 |
https://docs.brightdata.com/llms.txt |
文档索引 |
https://docs.brightdata.com/scraping-automation/scraping-browser/quickstart |
Browser API 设置 |
https://docs.brightdata.com/datasets/introduction |
网页爬虫工具 API:触发、轮询、下载 |
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、网络解锁器和 Browser API 预先配置的区域。
令牌会过期吗?
默认有效期大约为一年。注册响应不会返回确切的到期时间。
智能体可以创建自己的区域吗?
不能。该令牌对管理和账单仅有只读权限。智能体所需的三个区域会被预先配置。
智能体可以撤销自己的凭证吗?
不能。智能体不会发起撤销操作。如果凭证返回 401,请将其丢弃并重新执行发现流程。
智能体可以使用住宅代理吗?
不能。住宅代理始终需要通过控制面板使用已完成 KYC 验证的企业账户。
这是 ID-JAG 吗?
不是。这是 Bright Data 专有的智能体注册流程。
试用
让智能体访问 https://brightdata.com/auth.md 并要求它完成注册。三次调用后,它就能获得一个令牌、三个可用区域,以及每月 5,000 个免费积分。