Documentation de l’outil

Pourquoi un handle de domaine Bluesky est invalide, et comment le corriger

Comment Bluesky vérifie un handle de domaine : l’enregistrement TXT _atproto, le fichier atproto-did, le document DID, chaque vérification et les erreurs fréquentes.

Comment Bluesky vérifie un handle de domaine

Un handle est un nom de domaine. Bluesky accepte alice.example.com comme handle quand il peut vérifier le lien dans les deux sens :

  1. Le domaine pointe vers votre compte. Soit un enregistrement DNS TXT nommé _atproto.alice.example.com dont la valeur est did= suivi de votre DID, soit le fichier https://alice.example.com/.well-known/atproto-did dont le seul contenu est votre DID. L’un des deux suffit.
  2. Votre compte pointe vers le domaine. Votre document DID indique le handle dans alsoKnownAs, sous la forme at://alice.example.com. Bluesky l’y écrit quand vous changez de handle dans l’application.

Les règles sont dans la spécification des handles de l’AT Protocol. Pour les autres façons d’obtenir un handle, lisez le guide Comment obtenir un handle personnalisé sur Bluesky.

L’enregistrement à ajouter

HandleHôte / NomTypeValeur
example.com_atprotoTXTdid=did:plc:ewvi7nxzyoun6zhxrhs64oiz
alice.example.com (zone example.com)_atproto.aliceTXTdid=did:plc:ewvi7nxzyoun6zhxrhs64oiz

Les interfaces DNS ajoutent votre zone au nom d’elles-mêmes : saisissez la partie de _atproto.<handle> qui précède la zone, et non le nom complet. Le vérificateur trouve la zone par une requête SOA et affiche l’hôte exact. La valeur commence par did=, sans guillemets ni espaces : Bluesky lit une seule valeur qui commence par did=, telle quelle, sans rien retirer.

Le fichier est l’autre méthode, pour un hébergement sans interface DNS. C’est du texte brut, servi avec le statut 200 :

text
did:plc:ewvi7nxzyoun6zhxrhs64oiz

Ce que vérifie l’outil

L’outil fait sept vérifications, dans l’ordre. Chacune réussit, échoue, avertit ou n’est pas faite, avec un code de raison (les réponses de l’API et du MCP donnent ce code dans checks[].reason).

VérificationÉchoue quand (raison)
syntaxle domaine n’est pas un handle valide : plus de 253 caractères (too_long), une seule partie (single_label), une partie vide ou de plus de 63 caractères (label_length), un caractère autre que a–z, 0–9 et - (characters), un tiret au début ou à la fin d’une partie (hyphen), un domaine de premier niveau qui commence par un chiffre (tld_digit), un domaine de premier niveau réservé comme .local ou .example (disallowed_tld)
dnsaucun enregistrement (missing), une espace avant did=, que Bluesky lit comme une absence d’enregistrement (leading_space), un DID sans did= (no_prefix), une valeur qui n’est pas did= et un DID valide (invalid_value), l’enregistrement sur le mauvais nom (wrong_host : la zone deux fois, le _atproto de la zone elle-même, ou le domaine lui-même), deux valeurs ou plus qui commencent par did=, même identiques (conflict)
httpsaucun fichier (missing : un 404 ou un 410), une page web au lieu du DID (html), plus que le DID (extra_content), un contenu de plus de 1 Ko (too_large), un autre statut (status) ; avertit quand le serveur ne répond pas (unreachable)
agreementl’enregistrement et le fichier donnent des DID différents (disagree)
documentle document DID déclare un autre handle ou aucun (claims_other), ou n’existe pas (not_found)
expectedle domaine pointe vers un autre compte que celui indiqué (mismatch)
appviewBluesky affiche handle.invalid (invalid), l’ancien handle (old_handle), ou ne fait pas encore correspondre le domaine au compte (unresolved)

Une méthode absente ne pose pas de problème quand l’autre fonctionne : la ligne réussit alors avec not_needed. Un problème sur la méthode que Bluesky n’utilise pas est un avertissement, sauf deux valeurs DNS qui commencent par did=, que le résolveur de Bluesky traite comme un échec. Le DNS l’emporte, comme dans la spécification : un DID donné par le DNS et déclaré en retour par le document DID vérifie le handle, quoi que réponde le serveur web.

Erreurs fréquentes

  • La zone ajoutée deux fois. Une interface DNS ajoute votre zone au nom : saisir le nom complet _atproto.alice.example.com crée _atproto.alice.example.com.example.com. Saisissez seulement l’hôte que montre le vérificateur (_atproto.alice dans la zone example.com).
  • L’enregistrement sur le nom de la zone. Pour alice.example.com, un enregistrement sur _atproto.example.com désigne le handle example.com, pas le vôtre. Le vérificateur cherche un enregistrement did= à cet endroit, sur la zone ajoutée deux fois et sur le domaine lui-même.
  • Le DID sans did=. La valeur doit être did=did:plc:…, préfixe compris.
  • Une espace avant did=. Bluesky lit la valeur telle quelle : did=… compte comme une absence d’enregistrement.
  • Un ancien enregistrement oublié. Bluesky lit une seule valeur qui commence par did= : deux, même avec le même DID, rendent le handle invalide. Ne gardez que le vôtre.
  • Une page web au lieu du fichier. Beaucoup d’hébergeurs répondent à toute adresse inconnue avec leur page d’accueil, statut 200. Le fichier doit contenir le DID seul.
  • Le handle pas encore changé. Les enregistrements sont bons, mais votre document DID déclare encore l’ancien handle : définissez de nouveau le handle dans Paramètres → Compte → Handle dans l’application Bluesky.
  • L’attente du DNS. Un changement peut mettre jusqu’à une heure à atteindre tous les résolveurs. L’outil ne garde jamais de réponse en cache : relancez-le.

Pas de DNS pour un bot

Un bot peut prendre un handle name.bluesky.bot à la place : Bluesky.bot sert le fichier et change le handle pour vous. Voir Obtenir votre handle, ou vérifiez si un nom est libre avec le vérificateur de disponibilité de handle.

L’utiliser depuis du code

Le vérificateur est aussi une route d’API gratuite et un outil MCP, check_custom_handle :

bash
curl "https://bluesky.bot/api/v1/tools/custom-handle-checker?domain=alice.example.com"

Chaque appel compte pour 2 dans les limites. Voir API des outils et serveur MCP.

Vérificateur de handle de domaine

Découvrez pourquoi votre handle est invalide, et comment le corriger.