Registro Agêntico: Como um Agente de IA se Cadastra no Bright Data Com auth.md

TL;DR

Um agente de IA pode criar uma conta Bright Data e receber um token de API funcional sem que um humano preencha um formulário de cadastro. O protocolo está em https://brightdata.com/auth.md e é anunciado nos metadados de descoberta sob um bloco agent_auth.

Três chamadas:

1. POST /users/auth/agent_registration/auth com o e-mail do usuário. Retorna um claim_token. Ainda sem credencial.
2. O usuário lê um código de 6 caracteres da caixa de entrada e o fornece ao agente.
3. POST /users/auth/agent_registration/claim/complete com o claim_token e o código. Retorna o token de API.

A conta começa com 5.000 créditos gratuitos por mês, um crédito de teste de US$ 2 válido por 7 dias e três zonas pré-criadas: agent_serp, agent_unlocker, agent_browser_api. A primeira chamada a qualquer uma delas funciona sem nenhuma configuração.

O problema

Todo formulário de cadastro pressupõe um humano. Escolher um plano, clicar em um link de verificação, abrir um painel, encontrar configurações, copiar uma chave, colá-la em algum lugar.

Isso quebra quando quem precisa da chave é um agente. Um agente de codificação encarregado de extrair preços de 40 varejistas pode escrever o scraper, lidar com novas tentativas e analisar a saída. Mas não pode clicar em um botão em um navegador que não possui.

Então ele para no passo zero. E essa parada é mais difícil do que parece, porque o obstáculo não é capacidade.

O agente não tem permissão, mesmo quando consegue

A objeção óbvia é que a automação de navegador resolve isso. Dê ao agente uma extensão do Chrome ou uma sessão do Playwright e ele poderá preencher um formulário de cadastro como qualquer pessoa.

Ele pode. Mas não tem permissão.

Os agentes de navegador da Anthropic são proibidos de criar contas em nome de um usuário. Isso não é uma preferência leve nem uma solicitação de permissão. A criação de contas está na lista de proibições junto com o manuseio de dados bancários e exclusões permanentes, o que significa que é recusada mesmo quando o usuário pede explicitamente e concede permissão. A instrução é direcionar o usuário para criar a conta ele mesmo.

Duas outras regras tornam um formulário de cadastro quase inutilizável mesmo sem essa restrição. O Claude respeita sistemas de detecção de bots e verificação humana e não os completa em nome de um usuário. E aceitar termos, condições ou acordos exige aprovação explícita do usuário a cada vez, conforme a documentação de segurança publicada pela Anthropic. Um formulário de cadastro padrão pede a um agente que faça as três coisas de uma vez: criar uma conta, resolver um CAPTCHA e aceitar um termo de uso.

Esse é um limite razoável a se estabelecer. Um agente capaz de registrar contas silenciosamente contra endereços de e-mail arbitrários é uma máquina de abuso. A restrição existe por boas razões e não será relaxada.

A consequência para um provedor de dados é específica. Um formulário de cadastro não é um caminho lento para um agente. É um caminho fechado. Dar um navegador ao agente não ajuda, porque o navegador nunca foi o bloqueio.

O auth.md coloca o consentimento onde a política exige. O fluxo nunca pede ao agente que se passe por um humano. O agente faz chamadas HTTP. O humano recupera um código único de sua própria caixa de entrada e o repassa. A conta não pode ser criada sem a participação ativa do usuário, então o usuário não pode desconhecer que isso aconteceu. O agente é um cliente, não um substituto.

É por isso que a etapa de OTP está no protocolo em vez de ser eliminada por engenharia. Não é um atrito residual de um fluxo de cadastro humano. É o mecanismo de consentimento, e é o que torna isso algo que um agente tem permissão para concluir, em vez de apenas ser capaz de concluir.

Como um agente o encontra

Um agente que nunca viu o Bright Data pode chegar ao fluxo a partir de metadados padrão.

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

A resposta carrega um bloco 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"]
    }
  }
}

Esse bloco é o contrato. github_token e anonymous aparecerão ali se e quando forem lançados. Use apenas os métodos listados nos metadados, não métodos lembrados de uma cópia antiga do documento.

Há também metadados de recurso protegido para a 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"]
}

Os endpoints se autodocumentam em tempo de execução. GET https://brightdata.com/users/auth/agent_registration retorna uma cópia em markdown legível por máquina dos contratos de endpoint e da tabela de erros. Se essa resposta e o auth.md divergirem, a resposta do endpoint é a verdade ao vivo. Pode ser desligada independentemente, caso em que retorna instructions_disabled com um 404 e o agente recorre ao auth.md.

Quatro caminhos de entrada

O registro programático é o caminho totalmente automatizado. Não é o único.

O restante deste guia cobre o primeiro caminho.

Etapa 1: Descobrir

Leia os metadados do servidor de autorização e confirme quais tipos de assertion estão ativos. Hoje é apenas verified_email.

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

Etapa 2: Registrar

Use o endereço de e-mail real do usuário. Domínios descartáveis e endereços com alias plus, como [email protected], são rejeitados.

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 é opcional, mas recomendado. Declarar o nome do agente, até 100 caracteres, dá ao suporte e diagnósticos algo com que trabalhar.

A resposta não carrega credencial:

{
  "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 é um UUID v4 e é o próprio identificador do registro. Não há um registration_id separado. Mantenha-o em memória e passe-o para a etapa 3 como está.

Antes de enviar qualquer identidade do usuário, mostre ao usuário o nome do serviço, Bright Data, e o que a conta poderá fazer. Chamar esses endpoints assume a aceitação dos Termos de Serviço e da Política de Uso Aceitável do Bright Data em nome do endereço de e-mail fornecido.

Etapa 3: Verificar

O Bright Data envia por e-mail ao usuário um código alfanumérico de 6 caracteres, com maiúsculas e minúsculas, válido por 10 minutos por padrão. Peça ao usuário que o leia de volta.

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

A credencial é emitida aqui:

{
  "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" }
  }
}

Para reenviar o código, envie o claim_token para /users/auth/agent_registration/claim. Isso invalida o código anterior, não reinicia a contagem de tentativas restantes e é limitado a 3 reenvios por registro com intervalo mínimo de 60 segundos.

A conta agora está ativa no plano gratuito, mais o crédito de teste de US$ 2. Registros pendentes nunca verificados expiram após 24 horas.

Etapa 4: Usar a credencial

Busca na web através da zona 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"
  }'

Extraia uma página protegida através do 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"
  }'

Para a Browser API, conecte o Playwright, Puppeteer ou Selenium via CDP à zona agent_browser_api. Isso consome o crédito de teste de US$ 2. A configuração está em https://docs.brightdata.com/scraping-automation/scraping-browser/quickstart.

Para o conjunto completo de ferramentas MCP, use https://mcp.brightdata.com/mcp?token=<api_token>.

As Web Scraper APIs não são baseadas em zonas e não são provisionadas automaticamente pelo registro. Elas funcionam por meio de um mecanismo separado de acionamento, consulta e download, documentado em https://docs.brightdata.com/datasets/introduction.

O que a conta recebe

Não incluído: redes de proxy, administração de conta e criação ou edição de zonas. Proxies residenciais sempre exigem uma conta empresarial com Verificação KYC através do Painel de Controle. O humano pode adicionar fundos e remover restrições ali a qualquer momento.

O perfil de permissão do token é deliberadamente mínimo. É somente leitura para administração e faturamento e não pode criar ou editar zonas, razão pela qual as três de que precisa já vêm pré-provisionadas.

Sete comportamentos que quebram implementações ingênuas

Estas são as partes que um agente erra se tratar o fluxo como um formulário de cadastro genérico.

Um 200 na etapa 2 não é prova de que o e-mail é novo. Se o endereço já pertence a uma conta Bright Data, ou é filtrado por um domínio ou lista de permissões de e-mail durante um lançamento controlado, o formato da resposta é idêntico ao de sucesso e nenhum código é enviado. O proprietário da conta existente recebe, em vez disso, um e-mail de aviso separado. Isso é intencional e indistinguível do sucesso. Se um usuário relatar que nunca recebeu um código, peça que verifique o spam e confirme que ainda não possui conta, em vez de tentar repetidamente.

Repetir a etapa 2 não reinicia nada. Chamar /auth novamente para o mesmo e-mail enquanto um registro está pendente retorna o mesmo claim_token e os mesmos timestamps de expiração. Use o endpoint de reenvio para obter um código novo.

O provisionamento de zonas é por produto e falha de forma independente. Verifique cada entrada em zones. Um produto reportando "status": "failed" enquanto os outros têm sucesso significa que deve tentar aquele produto novamente mais tarde, não que o registro inteiro falhou.

/claim/complete é idempotente. Tentar novamente com o mesmo claim_token e código após um timeout ou erro de rede retorna o resultado idêntico. Não cria uma segunda conta, não emite uma segunda credencial nem concede direitos duplicados. Tente novamente com segurança.

A credencial é um segredo. Nunca imprima, registre ou ecoe o credential.token na saída de chat, transcrições, argumentos de linha de comando ou qualquer arquivo que uma parte não intencionada possa ler. Armazene-o em um gerenciador de segredos, um armazenamento de credenciais do SO, ou um arquivo .env excluído do controle de versão com permissões restritivas. Nunca em código-fonte em texto simples, histórico de shell ou logs.

Os limites de taxa se aplicam em cinco dimensões. Padrões: 3 inícios de registro por hora por e-mail, 60 por hora por IP de origem, 30 por hora por faixa de rede, 50 por hora por domínio de e-mail, 1.000 por hora globalmente. Exceder qualquer um deles retorna rate_limited. Os registros também passam por triagem de fraude.

Um 401 em uma credencial que funcionava significa reiniciar a descoberta. Descarte a credencial e volte para a etapa 1. Não tente novamente a chamada.

Códigos de erro

Toda resposta não-2xx de /auth, /claim e /claim/complete usa o mesmo formato: {"error": "<code>", "error_description": "<actionable next step>"}. A descrição é um próximo passo, não uma prosa. Nenhum limite interno de fraude, pontuação ou nome de fornecedor jamais é incluído.

Tente novamente 5xx com backoff exponencial. Não repita a mesma carga 4xx a menos que a tabela diga para fazer isso.

Revogação

Agentes não iniciam a revogação. Não existe endpoint para um agente devolver uma credencial.

Se uma credencial parar de funcionar e a API retornar 401, descarte-a e reinicie a descoberta a partir da etapa 1. Esse é o contrato inteiro. Um agente com um token morto não deve tentá-lo novamente, não deve tentar renová-lo e não deve supor que a conta desapareceu. Deve voltar aos metadados e começar de novo.

Reivindicando a conta depois

Um humano pode completar o cadastro padrão depois, com senha, GitHub ou Google, usando o mesmo endereço de e-mail, e obter acesso completo a essa mesma conta. Isso não cria uma duplicata e não invalida a credencial que o agente já está usando. A redefinição de senha nesse endereço é a forma de entrar no Painel de Controle a partir do zero.

Ainda não lançado

Declarado explicitamente para que os agentes não tentem e desperdicem uma solicitação.

A assertion de token do GitHub está planejada e sem data definida. O design lê o token de um GitHub CLI autenticado, o valida junto ao servidor do GitHub, lê o e-mail principal verificado e identifica a conta pelo ID numérico do GitHub. O token é usado uma vez e nunca armazenado. Como a identidade já está verificada, a credencial retorna imediatamente sem etapa de código. Os escopos mínimos seriam read:user e user:email, e uma conta do GitHub sem e-mail principal verificado seria rejeitada.

Nada disso está implementado. O servidor aceita apenas verified_email e rejeita qualquer outro valor como invalid_request. Os códigos invalid_github_token e email_unverified estão reservados e não são retornados hoje.

O registro anônimo está planejado e sem data definida.

A regra é a mesma para ambos: leia assertion_types_supported dos metadados e use apenas o que está listado. Quando forem lançados, os metadados são onde aparecerão primeiro.

Referência

Cada URL do protocolo:

CLI: npm install -g @brightdata/cli

SDKs: npm install @brightdata/sdk ou pip install brightdata-sdk

Perguntas frequentes

Um agente de IA pode criar uma conta Bright Data sem um humano?

Quase inteiramente. O agente faz todas as chamadas HTTP. A única ação do humano é ler um código de 6 caracteres do seu e-mail e fornecê-lo ao agente. Sem formulário, sem painel, sem navegador.

Por que o agente não pode simplesmente preencher o formulário de cadastro normal com uma ferramenta de navegador?

Porque não tem permissão. A Anthropic proíbe que seus agentes de navegador criem contas em nome de um usuário, mesmo com permissão explícita do usuário, e separadamente instrui que não completem CAPTCHAs ou verificações humanas. Um formulário de cadastro pede ambos. O fluxo do auth.md evita isso nunca pedindo ao agente que se passe por humano.

Onde o protocolo está documentado?

https://brightdata.com/auth.md, espelhado em formato legível por máquina em https://brightdata.com/users/auth/agent_registration.

Como um agente descobre os endpoints?

A partir do bloco agent_auth em https://brightdata.com/.well-known/oauth-authorization-server.

O que o agente recebe?

Um token de API padrão da Bright Data, 5.000 créditos gratuitos por mês, um crédito de teste de US$ 2 válido por 7 dias e três zonas pré-provisionadas para SERP, Web Unlocker e Browser API.

O token expira?

Cerca de um ano por padrão. O vencimento exato não é retornado na resposta do registro.

O agente pode criar suas próprias zonas?

Não. O token é somente leitura para administração e faturamento. As três zonas de que precisa já vêm pré-provisionadas.

O agente pode revogar sua própria credencial?

Não. Agentes não iniciam a revogação. Se uma credencial retornar 401, descarte-a e reinicie a descoberta.

O agente pode usar proxies residenciais?

Não. Esses sempre exigem uma conta empresarial com Verificação KYC através do Painel de Controle.

Isso é ID-JAG?

Não. É um fluxo de registro de agente proprietário da Bright Data.

Experimente

Direcione um agente para https://brightdata.com/auth.md e peça que ele se registre. Três chamadas depois, ele tem um token, três zonas funcionais e 5.000 créditos gratuitos por mês.