Inscription agentique : comment un agent IA s’inscrit à Bright Data avec auth.md

TL;DR

Un agent IA peut créer un compte Bright Data et recevoir un jeton API fonctionnel sans qu’un humain remplisse un formulaire d’inscription. Le protocole se trouve à https://brightdata.com/auth.md et est annoncé dans les métadonnées de découverte sous un bloc agent_auth.

Trois appels :

1. POST /users/auth/agent_registration/auth avec l’email de l’utilisateur. Renvoie un claim_token. Pas encore d’identifiant.
2. L’utilisateur lit un code à 6 caractères dans sa boîte mail et le donne à l’agent.
3. POST /users/auth/agent_registration/claim/complete avec le claim_token et le code. Renvoie le jeton API.

Le compte démarre avec 5 000 crédits gratuits par mois, un crédit d’essai de 2 $ valable 7 jours, et trois zones pré-créées : agent_serp, agent_unlocker, agent_browser_api. Le premier appel à l’une d’elles fonctionne sans aucune configuration.

Le problème

Chaque formulaire d’inscription suppose un humain. Choisir un plan, cliquer sur un lien de vérification, ouvrir un tableau de bord, trouver les paramètres, copier une clé, la coller quelque part.

Cela casse quand l’élément ayant besoin de la clé est un agent. Un agent de codage chargé de récupérer les prix de 40 détaillants peut écrire le scraper, gérer les nouvelles tentatives et analyser la sortie. Il ne peut pas cliquer sur un bouton dans un navigateur qu’il n’a pas.

Il s’arrête donc à l’étape zéro. Et cet arrêt est plus difficile qu’il n’y paraît, car l’obstacle n’est pas une question de capacité.

L’agent n’y est pas autorisé, même s’il en est capable

L’objection évidente est que l’automatisation du navigateur résout ce problème. Donnez à l’agent une extension Chrome ou une session Playwright et il peut remplir un formulaire d’inscription comme n’importe qui.

Il le peut. Il n’y est pas autorisé.

Les agents de navigateur d’Anthropic ont l’interdiction de créer des comptes au nom d’un utilisateur. Ce n’est pas une préférence souple ni une invite de permission. La création de compte figure sur la liste des actions interdites, aux côtés de la gestion des données bancaires et des suppressions permanentes, ce qui signifie qu’elle est refusée même lorsque l’utilisateur le demande explicitement et donne son autorisation. La consigne est de diriger l’utilisateur vers la création du compte lui-même.

Deux autres règles rendent un formulaire d’inscription pratiquement inutilisable, même sans celle-ci. Claude respecte la détection de bots et les systèmes de vérification humaine et ne les complète pas au nom d’un utilisateur. Et accepter des conditions, des termes ou des accords nécessite l’approbation explicite de l’utilisateur à chaque fois, selon la documentation de sécurité publiée d’Anthropic. Un formulaire d’inscription standard demande à un agent de faire les trois à la fois : créer un compte, résoudre un CAPTCHA et accepter des CGU.

C’est une limite raisonnable à poser. Un agent capable d’enregistrer silencieusement des comptes contre des adresses email arbitraires est un moteur d’abus. Cette restriction existe pour de bonnes raisons et ne sera pas assouplie.

La conséquence pour un fournisseur de données est précise. Un formulaire d’inscription n’est pas une voie lente pour un agent. C’est une voie fermée. Donner un navigateur à l’agent n’aide pas, car le navigateur n’a jamais été le blocage.

auth.md place le consentement là où la politique l’exige. Le flux ne demande jamais à l’agent de se faire passer pour un humain. L’agent effectue des appels HTTP. L’humain récupère un code à usage unique dans sa propre boîte mail et le transmet. Le compte ne peut pas être créé sans la participation active de l’utilisateur, donc l’utilisateur ne peut pas ignorer que cela s’est produit. L’agent est un client, pas un substitut.

C’est pourquoi l’étape OTP fait partie du protocole plutôt que d’être conçue pour disparaître. Ce n’est pas une friction résiduelle d’un flux d’inscription humain. C’est le mécanisme de consentement, et c’est ce qui fait que c’est quelque chose qu’un agent est autorisé à accomplir plutôt que simplement capable d’accomplir.

Comment un agent le trouve

Un agent qui n’a jamais vu Bright Data peut accéder au flux à partir de métadonnées standard.

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

La réponse contient un bloc 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"]
    }
  }
}

Ce bloc est le contrat. github_token et anonymous y apparaîtront si et quand ils seront déployés. N’utilisez que les méthodes listées dans les métadonnées, pas celles mémorisées d’une ancienne copie du document.

Il existe également des métadonnées de ressource protégée pour l’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"]
}

Les points de terminaison s’auto-documentent à l’exécution. GET https://brightdata.com/users/auth/agent_registration renvoie une copie markdown lisible par machine des contrats de points de terminaison et du tableau d’erreurs. Si cette réponse et auth.md divergent un jour, la réponse du point de terminaison fait foi. Elle peut être désactivée indépendamment, auquel cas elle renvoie instructions_disabled avec un 404 et l’agent se rabat sur auth.md.

Quatre voies d’accès

L’inscription programmatique est la voie entièrement automatisée. Ce n’est pas la seule.

Le reste de ce guide couvre la première.

Étape 1 : Découverte

Lisez les métadonnées du serveur d’autorisation et confirmez quels types d’assertion sont actifs. Aujourd’hui, c’est verified_email uniquement.

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

Étape 2 : Inscription

Utilisez la véritable adresse email de l’utilisateur. Les domaines jetables et les adresses avec alias plus comme [email protected] sont rejetés.

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 est facultatif mais recommandé. Déclarer le nom de l’agent, jusqu’à 100 caractères, donne au support et aux diagnostics quelque chose à exploiter.

La réponse ne contient aucun identifiant :

{
  "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 est un UUID v4 et constitue l’identifiant propre de l’inscription. Il n’y a pas de registration_id séparé. Conservez-le en mémoire et transmettez-le tel quel à l’étape 3.

Avant d’envoyer toute identité utilisateur, montrez à l’utilisateur le nom du service, Bright Data, et ce que le compte pourra faire. Appeler ces points de terminaison affirme l’acceptation des Conditions d’utilisation et de la Politique d’utilisation acceptable de Bright Data au nom de l’adresse email fournie.

Étape 3 : Vérification

Bright Data envoie par email à l’utilisateur un code alphanumérique à 6 caractères, en casse mixte, valable 10 minutes par défaut. Demandez à l’utilisateur de le relire.

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

L’identifiant est délivré ici :

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

Pour renvoyer le code, postez le claim_token à /users/auth/agent_registration/claim. Cela invalide le code précédent, ne réinitialise pas le nombre de tentatives restantes, et est limité à 3 renvois par inscription avec un intervalle minimum de 60 secondes.

Le compte est maintenant actif sur le niveau gratuit plus le crédit d’essai de 2 $. Les inscriptions en attente jamais vérifiées expirent après 24 heures.

Étape 4 : Utiliser l’identifiant

Recherche web via la zone 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"
  }'

Scraper une page protégée via 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"
  }'

Pour l’API Navigateur, connectez Playwright, Puppeteer ou Selenium via CDP à la zone agent_browser_api. Cela consomme le crédit d’essai de 2 $. La configuration se trouve sur https://docs.brightdata.com/scraping-automation/scraping-browser/quickstart.

Pour l’ensemble complet des outils MCP, utilisez https://mcp.brightdata.com/mcp?token=<api_token>.

Les Web Scraper APIs ne sont pas basées sur des zones et ne sont pas auto-provisionnées par l’inscription. Elles fonctionnent via un mécanisme séparé de déclenchement, sondage et téléchargement documenté sur https://docs.brightdata.com/datasets/introduction.

Ce que le compte obtient

Non inclus : les réseaux de proxy, l’administration de compte, et la création ou modification de zones. Les proxys résidentiels nécessitent toujours un compte professionnel vérifié par KYC via le Panneau de contrôle. L’humain peut y ajouter des fonds et lever les restrictions à tout moment.

Le profil de permissions du jeton est délibérément minimal. Il est en lecture seule pour l’administration et la facturation, et ne peut pas créer ni modifier de zones, c’est pourquoi les trois dont il a besoin sont pré-provisionnées.

Sept comportements qui cassent les implémentations naïves

Ce sont les éléments qu’un agent se trompe s’il traite le flux comme un formulaire d’inscription générique.

Un 200 à l’étape 2 ne prouve pas que l’email est nouveau. Si l’adresse appartient déjà à un compte Bright Data, ou est filtrée par une liste d’autorisation de domaine ou d’email lors d’un déploiement contrôlé, la forme de la réponse est identique à un succès et aucun code n’est envoyé. Le propriétaire du compte existant reçoit à la place un email de notification séparé. C’est intentionnel et indiscernable d’un succès. Si un utilisateur signale ne jamais avoir reçu de code, demandez-lui de vérifier les spams et de confirmer qu’il n’a pas déjà de compte, plutôt que de relancer en boucle.

Répéter l’étape 2 ne redémarre rien. Appeler à nouveau /auth pour le même email alors qu’une inscription est en attente renvoie le même claim_token et des horodatages d’expiration inchangés. Utilisez le point de terminaison de renvoi pour obtenir un nouveau code.

Le provisionnement de zone est par produit et échoue indépendamment. Vérifiez chaque entrée sous zones. Un produit signalant "status": "failed" pendant que les autres réussissent signifie qu’il faut réessayer ce produit plus tard, pas que l’inscription entière a échoué.

/claim/complete est idempotent. Réessayer avec le même claim_token et le même code après un délai d’attente ou une erreur réseau renvoie un résultat identique. Cela ne crée pas de second compte, n’émet pas de second identifiant, et n’accorde pas de droits deux fois. Réessayez en toute sécurité.

L’identifiant est un secret. Ne jamais imprimer, journaliser ou répéter credential.token dans une sortie de chat, des transcriptions, des arguments de ligne de commande, ou tout fichier qu’une partie non prévue pourrait lire. Stockez-le dans un gestionnaire de secrets, un magasin d’identifiants du système d’exploitation, ou un fichier .env exclu du contrôle de version avec des permissions restrictives. Pas en texte brut dans le code source, l’historique du shell, ou les journaux.

Les limites de débit s’appliquent sur cinq dimensions. Valeurs par défaut : 3 démarrages d’inscription par heure par email, 60 par heure par IP source, 30 par heure par plage réseau, 50 par heure par domaine email, 1 000 par heure globalement. Dépasser l’une d’elles renvoie rate_limited. Les inscriptions passent également par un filtrage anti-fraude.

Un 401 sur un identifiant fonctionnel signifie redémarrer la découverte. Abandonnez l’identifiant et revenez à l’étape 1. Ne réessayez pas l’appel.

Codes d’erreur

Chaque réponse non-2xx de /auth, /claim, et /claim/complete utilise la même forme : {"error": "<code>", "error_description": "<étape suivante actionnable>"}. La description est une étape suivante, pas de la prose. Aucun seuil interne de fraude, score, ou nom de fournisseur n’est jamais inclus.

Réessayez les erreurs 5xx avec un recul exponentiel. Ne réessayez pas la même charge utile 4xx sauf indication contraire dans le tableau.

Révocation

Les agents n’initient pas la révocation. Il n’existe aucun point de terminaison permettant à un agent de restituer un identifiant.

Si un identifiant cesse de fonctionner et que l’API renvoie 401, abandonnez-le et redémarrez la découverte depuis l’étape 1. C’est tout le contrat. Un agent détenant un jeton mort ne doit pas le réessayer, ne doit pas tenter de le rafraîchir, et ne doit pas supposer que le compte a disparu. Il doit revenir aux métadonnées et recommencer.

Réclamer le compte plus tard

Un humain peut compléter l’inscription standard plus tard, avec un mot de passe, GitHub, ou Google, en utilisant la même adresse email, et obtenir un accès complet à ce même compte. Cela ne crée pas de doublon et n’invalide pas l’identifiant que l’agent utilise déjà. La réinitialisation du mot de passe sur cette adresse est le moyen d’accéder au Panneau de contrôle à froid.

Pas encore déployé

Énoncé explicitement afin que les agents ne tentent pas cela et ne gaspillent pas une requête.

L’assertion par jeton GitHub est prévue mais non planifiée. La conception lit le jeton depuis un CLI GitHub authentifié, le valide côté serveur auprès de GitHub, lit l’email principal vérifié, et identifie le compte par l’ID numérique GitHub. Le jeton est utilisé une seule fois et jamais stocké. Comme l’identité est déjà vérifiée, l’identifiant est renvoyé immédiatement sans étape de code. Les portées minimales seraient read:user et user:email, et un compte GitHub sans email principal vérifié serait rejeté.

Rien de tout cela n’est implémenté. Le serveur n’accepte que verified_email et rejette tout le reste comme invalid_request. Les codes invalid_github_token et email_unverified sont réservés et non renvoyés aujourd’hui.

L’inscription anonyme est prévue mais non planifiée.

La règle est la même pour les deux : lisez assertion_types_supported depuis les métadonnées et n’utilisez que ce qui est listé. Lorsqu’elles seront déployées, les métadonnées sont l’endroit où elles apparaîtront en premier.

Référence

Chaque URL du protocole :

CLI : npm install -g @brightdata/cli

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

FAQ

Un agent IA peut-il créer un compte Bright Data sans humain ?

Presque entièrement. L’agent effectue chaque appel HTTP. La seule action de l’humain est de lire un code à 6 caractères dans son email et de le donner à l’agent. Pas de formulaire, pas de tableau de bord, pas de navigateur.

Pourquoi l’agent ne peut-il pas simplement remplir le formulaire d’inscription normal avec un outil de navigateur ?

Parce qu’il n’y est pas autorisé. Anthropic interdit à ses agents de navigateur de créer des comptes au nom d’un utilisateur, même avec une permission explicite de l’utilisateur, et leur ordonne séparément de ne pas compléter de CAPTCHA ou de vérification humaine. Un formulaire d’inscription demande les deux. Le flux auth.md évite cela en ne demandant jamais à l’agent d’agir comme un humain.

Où ce protocole est-il documenté ?

https://brightdata.com/auth.md, reflété sous forme lisible par machine à https://brightdata.com/users/auth/agent_registration.

Comment un agent découvre-t-il les points de terminaison ?

À partir du bloc agent_auth dans https://brightdata.com/.well-known/oauth-authorization-server.

Que reçoit l’agent ?

Un jeton API Bright Data standard, 5 000 crédits gratuits par mois, un crédit d’essai de 2 $ valable 7 jours, et trois zones pré-provisionnées pour SERP, Web Unlocker, et l’API Navigateur.

Le jeton expire-t-il ?

De l’ordre d’un an par défaut. L’expiration exacte n’est pas renvoyée dans la réponse d’inscription.

L’agent peut-il créer ses propres zones ?

Non. Le jeton est en lecture seule pour l’administration et la facturation. Les trois zones dont il a besoin sont pré-provisionnées.

L’agent peut-il révoquer son propre identifiant ?

Non. Les agents n’initient pas la révocation. Si un identifiant renvoie 401, abandonnez-le et redémarrez la découverte.

L’agent peut-il utiliser des proxys résidentiels ?

Non. Ceux-ci nécessitent toujours un compte professionnel vérifié par KYC via le Panneau de contrôle.

S’agit-il d’ID-JAG ?

Non. C’est un flux d’inscription d’agent propriétaire de Bright Data.

Essayez-le

Pointez un agent vers https://brightdata.com/auth.md et demandez-lui de s’inscrire. Trois appels plus tard, il dispose d’un jeton, de trois zones fonctionnelles, et de 5 000 crédits gratuits par mois.