Registro Agéntico: Cómo un Agente de IA se Registra en Bright Data Con auth.md

TL;DR

Un agente de IA puede crear una cuenta de Bright Data y recibir un token de API funcional sin que un humano complete un formulario de registro. El protocolo vive en https://brightdata.com/auth.md y se anuncia en los metadatos de descubrimiento bajo un bloque agent_auth.

Tres llamadas:

1. POST /users/auth/agent_registration/auth con el correo del usuario. Devuelve un claim_token. Aún sin credencial.
2. El usuario lee un código de 6 caracteres de su bandeja de entrada y se lo da al agente.
3. POST /users/auth/agent_registration/claim/complete con el claim_token y el código. Devuelve el token de API.

La cuenta inicia con 5,000 créditos gratis al mes, un crédito de prueba de $2 válido por 7 días, y tres zonas precreadas: agent_serp, agent_unlocker, agent_browser_api. La primera llamada a cualquiera de ellas funciona sin configuración alguna.

El problema

Todo formulario de registro asume un humano. Elegir un plan, hacer clic en un enlace de verificación, abrir un panel, buscar configuraciones, copiar una clave, pegarla en algún lugar.

Eso falla cuando quien necesita la clave es un agente. Un agente de código al que se le pide extraer precios de 40 minoristas puede escribir el scraper, manejar reintentos y parsear la salida. No puede hacer clic en un botón en un navegador que no tiene.

Así que se detiene en el paso cero. Y la detención es más difícil de lo que parece, porque el obstáculo no es la capacidad.

Al agente no se le permite, aunque pueda

La objeción obvia es que la automatización de navegador resuelve esto. Dale al agente una extensión de Chrome o una sesión de Playwright y podrá llenar un formulario de registro como cualquiera.

Puede. No se le permite.

Los agentes de navegador de Anthropic tienen prohibido crear cuentas en nombre de un usuario. Esto no es una preferencia suave ni un aviso de permiso. La creación de cuentas está en la lista de prohibiciones junto con el manejo de datos bancarios y las eliminaciones permanentes, lo que significa que se rechaza incluso cuando el usuario lo pide explícitamente y otorga permiso. La instrucción es dirigir al usuario a crear la cuenta por sí mismo.

Dos reglas adicionales hacen que un formulario de registro sea casi inutilizable incluso sin esa. Claude respeta la detección de bots y los sistemas de verificación humana y no los completa en nombre del usuario. Y aceptar términos, condiciones o acuerdos requiere aprobación explícita del usuario cada vez, según la documentación de seguridad publicada de Anthropic. Un formulario de registro estándar le pide a un agente hacer las tres cosas a la vez: crear una cuenta, resolver un CAPTCHA y aceptar un ToS.

Esta es una línea razonable de trazar. Un agente que pueda registrar cuentas silenciosamente contra direcciones de correo arbitrarias es un motor de abuso. La restricción existe por buenas razones y no se va a relajar.

La consecuencia para un proveedor de datos es específica. Un formulario de registro no es un camino lento para un agente. Es un camino cerrado. Darle al agente un navegador no ayuda, porque el navegador nunca fue el bloqueo.

auth.md coloca el consentimiento donde la política lo necesita. El flujo nunca le pide al agente que se haga pasar por un humano. El agente hace llamadas HTTP. El humano recupera un código de un solo uso de su propia bandeja de entrada y lo entrega. La cuenta no se puede crear sin la participación activa del usuario, así que el usuario no puede desconocer que sucedió. El agente es un cliente, no un sustituto.

Por eso el paso del OTP está en el protocolo en lugar de ser eliminado por diseño. No es fricción sobrante de un flujo de registro humano. Es el mecanismo de consentimiento, y es lo que hace que esto sea algo que un agente tiene permitido completar, no solo algo que es capaz de completar.

Cómo lo encuentra un agente

Un agente que nunca ha visto Bright Data puede llegar al flujo desde metadatos estándar.

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

La respuesta lleva un bloque 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"]
    }
  }
}

Ese bloque es el contrato. github_token y anonymous aparecerán ahí si y cuando se lancen. Usa solo los métodos que lista el metadato, no métodos recordados de una copia anterior del documento.

También existe metadata de recurso protegido para la 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"]
}

Los endpoints se autodocumentan en tiempo de ejecución. GET https://brightdata.com/users/auth/agent_registration devuelve una copia en markdown legible por máquina de los contratos de endpoints y la tabla de errores. Si esa respuesta y auth.md alguna vez difieren, la respuesta del endpoint es la verdad vigente. Se puede desactivar de forma independiente, en cuyo caso devuelve instructions_disabled con un 404 y el agente recurre a auth.md.

Cuatro formas de entrar

El registro programático es el camino totalmente automatizado. No es el único.

El resto de esta guía cubre el primero.

Paso 1: Descubrir

Lee los metadatos del servidor de autorización y confirma qué tipos de aserción están activos. Hoy eso es solo verified_email.

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

Paso 2: Registrar

Usa la dirección de correo real del usuario. Los dominios desechables y las direcciones con alias plus, como [email protected], son rechazadas.

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 es opcional pero recomendado. Declarar el nombre del agente, hasta 100 caracteres, le da a soporte y diagnóstico algo con qué trabajar.

La respuesta no lleva 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 es un UUID v4 y es el identificador propio del registro. No hay un registration_id separado. Guárdalo en memoria y pásalo al paso 3 tal cual.

Antes de enviar cualquier identidad de usuario, muéstrale al usuario el nombre del servicio, Bright Data, y lo que la cuenta podrá hacer. Llamar a estos endpoints afirma la aceptación de los Términos de Servicio y la Política de Uso Aceptable de Bright Data en nombre de la dirección de correo proporcionada.

Paso 3: Verificar

Bright Data envía por correo al usuario un código alfanumérico de 6 caracteres, con mayúsculas y minúsculas, válido 10 minutos por defecto. Pide al usuario que lo lea en voz alta.

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

La credencial se emite aquí:

{
  "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 el código, envía el claim_token a /users/auth/agent_registration/claim. Eso invalida el código anterior, no reinicia el contador de intentos restantes, y está limitado a 3 reenvíos por registro con un intervalo mínimo de 60 segundos.

La cuenta ahora está activa en el nivel gratuito más el crédito de prueba de $2. Los registros pendientes que nunca se verifican expiran después de 24 horas.

Paso 4: Usar la credencial

Búsqueda web a través de la 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"
  }'

Extrae una página protegida a través de 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 el Browser API, conecta Playwright, Puppeteer o Selenium sobre CDP a la zona agent_browser_api. Esto consume del crédito de prueba de $2. La configuración está en https://docs.brightdata.com/scraping-automation/scraping-browser/quickstart.

Para el conjunto completo de herramientas MCP, usa https://mcp.brightdata.com/mcp?token=<api_token>.

Los Web Scraper APIs no se basan en zonas y no se aprovisionan automáticamente con el registro. Funcionan mediante un mecanismo separado de disparo, sondeo y descarga documentado en https://docs.brightdata.com/datasets/introduction.

Qué obtiene la cuenta

No incluido: redes de proxy, administración de cuenta, y creación o edición de zonas. Los proxies residenciales siempre requieren una cuenta empresarial verificada con KYC a través del Panel de Control. El humano puede agregar fondos y levantar restricciones ahí en cualquier momento.

El perfil de permisos del token es deliberadamente mínimo. Es de solo lectura para administración y facturación y no puede crear ni editar zonas, por eso las tres que necesita están preaprovisionadas.

Siete comportamientos que rompen implementaciones ingenuas

Estas son las partes que un agente hace mal si trata el flujo como un formulario de registro genérico.

Un 200 en el paso 2 no es prueba de que el correo es nuevo. Si la dirección ya pertenece a una cuenta de Bright Data, o está filtrada por un dominio o lista de permitidos durante un lanzamiento controlado, la forma de la respuesta es idéntica a la de éxito y no se envía código. El propietario de la cuenta existente recibe en su lugar un correo de aviso separado. Esto es intencional y no se puede distinguir del éxito. Si un usuario reporta que nunca recibió un código, pídele que revise spam y confirme que no tiene ya una cuenta, en lugar de reintentar en bucle.

Repetir el paso 2 no reinicia nada. Llamar a /auth de nuevo para el mismo correo mientras un registro está pendiente devuelve el mismo claim_token y marcas de expiración sin cambios. Usa el endpoint de reenvío para un código nuevo.

El aprovisionamiento de zonas es por producto y falla de forma independiente. Revisa cada entrada bajo zones. Que un producto reporte "status": "failed" mientras los otros tienen éxito significa reintentar ese producto más tarde, no que todo el registro falló.

/claim/complete es idempotente. Reintentar con el mismo claim_token y código después de un tiempo de espera o error de red devuelve el resultado idéntico. No crea una segunda cuenta, no emite una segunda credencial, ni otorga privilegios dos veces. Reintenta con seguridad.

La credencial es un secreto. Nunca imprimas, registres o reproduzcas credential.token en la salida del chat, transcripciones, argumentos de línea de comandos, o cualquier archivo que una parte no deseada pudiera leer. Guárdalo en un gestor de secretos, un almacén de credenciales del sistema operativo, o un archivo .env excluido del control de versiones con permisos restrictivos. No en código fuente en texto plano, historial de shell, o registros.

Los límites de tasa aplican en cinco dimensiones. Valores por defecto: 3 inicios de registro por hora por correo, 60 por hora por IP de origen, 30 por hora por rango de red, 50 por hora por dominio de correo, 1,000 por hora de forma global. Exceder cualquiera devuelve rate_limited. Los registros también pasan por revisión de fraude.

Un 401 en una credencial que funcionaba significa reiniciar el descubrimiento. Descarta la credencial y vuelve al paso 1. No reintentes la llamada.

Códigos de error

Toda respuesta no 2xx de /auth, /claim, y /claim/complete usa la misma forma: {"error": "<code>", "error_description": "<actionable next step>"}. La descripción es un siguiente paso, no prosa. Nunca se incluyen umbrales internos de fraude, puntuaciones o nombres de proveedores.

Reintenta los 5xx con retroceso exponencial. No reintentes el mismo payload 4xx a menos que la tabla indique hacerlo.

Revocación

Los agentes no inician la revocación. No hay un endpoint para que un agente devuelva una credencial.

Si una credencial deja de funcionar y la API devuelve 401, descártala y reinicia el descubrimiento desde el paso 1. Ese es todo el contrato. Un agente que tiene un token muerto no debe reintentarlo, no debe intentar renovarlo, y no debe asumir que la cuenta desapareció. Debe volver a los metadatos y comenzar de nuevo.

Reclamar la cuenta más tarde

Un humano puede completar el registro estándar más tarde, con una contraseña, GitHub, o Google, usando la misma dirección de correo, y obtener acceso completo a esa misma cuenta. No crea un duplicado ni invalida la credencial que el agente ya está usando. El restablecimiento de contraseña en esa dirección es la vía de entrada al Panel de Control desde cero.

Aún no disponible

Declarado explícitamente para que los agentes no lo intenten y desperdicien una solicitud.

La aserción de token de GitHub está planeada y sin fecha. El diseño lee el token de un CLI de GitHub autenticado, lo valida contra GitHub del lado del servidor, lee el correo primario verificado, y identifica la cuenta con el ID numérico de GitHub. El token se usa una vez y nunca se almacena. Como la identidad ya está verificada, la credencial se devuelve de inmediato sin paso de código. Los alcances mínimos serían read:user y user:email, y una cuenta de GitHub sin un correo primario verificado sería rechazada.

Nada de eso está implementado. El servidor acepta solo verified_email y rechaza cualquier otra cosa como invalid_request. Los códigos invalid_github_token y email_unverified están reservados y no se devuelven hoy.

El registro anónimo está planeado y sin fecha.

La regla es la misma para ambos: lee assertion_types_supported en los metadatos y usa solo lo que está listado. Cuando se lancen, los metadatos son donde aparecen primero.

Referencia

Cada URL en el protocolo:

CLI: npm install -g @brightdata/cli

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

Preguntas frecuentes

¿Puede un agente de IA crear una cuenta de Bright Data sin un humano?

Casi por completo. El agente hace cada llamada HTTP. La única acción del humano es leer un código de 6 caracteres de su correo y dárselo al agente. Sin formulario, sin panel, sin navegador.

¿Por qué el agente no puede simplemente llenar el formulario de registro normal con una herramienta de navegador?

Porque no se le permite. Anthropic prohíbe que sus agentes de navegador creen cuentas en nombre de un usuario, incluso con permiso explícito del usuario, y por separado les indica no completar CAPTCHAs ni verificación humana. Un formulario de registro pide ambas cosas. El flujo de auth.md evita esto al nunca pedirle al agente que actúe como humano.

¿Dónde está documentado el protocolo?

https://brightdata.com/auth.md, reflejado en forma legible por máquina en https://brightdata.com/users/auth/agent_registration.

¿Cómo descubre un agente los endpoints?

Desde el bloque agent_auth en https://brightdata.com/.well-known/oauth-authorization-server.

¿Qué obtiene el agente?

Un token de API estándar de Bright Data, 5,000 créditos gratis al mes, un crédito de prueba de $2 válido por 7 días, y tres zonas preaprovisionadas para SERP, Web Unlocker, y Browser API.

¿Expira el token?

Del orden de un año por defecto. La expiración exacta no se devuelve en la respuesta del registro.

¿Puede el agente crear sus propias zonas?

No. El token es de solo lectura para administración y facturación. Las tres zonas que necesita están preaprovisionadas.

¿Puede el agente revocar su propia credencial?

No. Los agentes no inician la revocación. Si una credencial devuelve 401, descártala y reinicia el descubrimiento.

¿Puede el agente usar proxies residenciales?

No. Esos siempre requieren una cuenta empresarial verificada con KYC a través del Panel de Control.

¿Es esto ID-JAG?

No. Es un flujo de registro de agentes propietario de Bright Data.

Pruébalo

Dirige a un agente a https://brightdata.com/auth.md y pídele que se registre. Tres llamadas después tiene un token, tres zonas funcionando, y 5,000 créditos gratis al mes.