Inscription en libre-service

La plupart des agents utilisent un compte que vous possédez déjà : vous configurez votre agent et il se connecte via le navigateur. Ce guide décrit l'autre chemin, où un agent sans compte en crée un lui-même, entièrement depuis le terminal. Utilisez CLI ou curl pour vérifier une adresse e-mail et créer une organisation, un espace de travail et un identifiant. Le serveur stdio local MCP nécessite un identifiant enregistré avant de pouvoir démarrer ; le serveur hébergé MCP n'expose pas les outils d'inscription. Vous devez avoir accès à la boîte de réception pour récupérer le code de vérification. Les inscriptions effectuées via Bird CLI ou le serveur MCP sont attribuées à l'outil qui les a réalisées.

Utiliser le CLI

Pour les commandes CLI ci-dessous, vous devez avoir installé le bird CLI. L'inscription et la vérification sont indépendantes de la région et ne nécessitent aucune configuration initiale. À la dernière étape, passez --region (us1 ou eu1) à create-org pour choisir où le compte et ses données résident. Aucun nom d'hôte ni variable d'environnement n'est requis.

1. Demander un code de connexion

bird auth signup envoie par e-mail un code de connexion à six chiffres. La vérification de ce code crée le compte si l'adresse e-mail est nouvelle. Le même parcours de lien magique sans mot de passe que le tableau de bord est utilisé, le code reçu par e-mail est donc tout ce dont vous avez besoin. Conservez l'adresse e-mail pour l'étape suivante.

Exemple de code

bird auth signup you@example.com
# { "email": "you@example.com", "status": "code_sent" }

2. Vérifier l'adresse e-mail

Le code à six chiffres arrive par e-mail, il provient donc de l'extérieur du CLI : lisez-le dans la boîte de réception. Transmettez-le avec la même adresse e-mail à bird auth verify-email, qui vous connecte et, pour un tout nouveau compte, renvoie un onboarding_ticket à usage unique.

Exemple de code

bird auth verify-email you@example.com --code 123456
# { "onboarding_ticket": "...", "user_id": "usr_..." }

3. Créer l'organisation

bird auth create-org consomme le ticket pour créer votre organisation et votre espace de travail, puis stocke l'identifiant généré afin que le CLI et le serveur stdio local MCP s'authentifient en tant que nouveau compte à partir de maintenant. L'opération est unique : un second appel renvoie 409. --region détermine où le compte et ses données résident (us1 ou eu1) et achemine l'appel vers cette région ; le CLI en déduit l'hôte, vous n'avez donc pas à définir d'URL.

Exemple de code

bird auth create-org "Acme" --workspace-name "Production" --region us1 --onboarding-ticket "YOUR_ONBOARDING_TICKET"

Vérifiez que l'identifiant fonctionne :

Exemple de code

bird auth status   # authenticated: true, valid: true

Le compte est actif et authentifié. L'agent peut désormais utiliser le CLI pour configurer des canaux et envoyer des messages.

Inspecter les entrées de CLI avant exécution

Chaque étape est auto-descriptive et ne nécessite aucun identifiant, un agent peut donc planifier l'ensemble du processus avant d'envoyer quoi que ce soit. bird auth --help affiche le flux ordonné, --example affiche un corps de requête prêt à modifier, et --response-schema affiche les champs renvoyés par chaque commande.

Utiliser curl

Vous avez besoin de curl et jq, mais pas de Bird CLI, de connexion MCP, de clé API ni de session navigateur. Exécutez les commandes dans le même shell, en vous arrêtant si une requête échoue. Choisissez us1 ou eu1 avant de commencer ; la requête de création de l'organisation doit être envoyée à l'hôte correspondant à son region.

Exemple de code

umask 077
BIRD_SIGNUP_DIR=$(mktemp -d)
BIRD_REGION=us1
BIRD_BASE_URL="https://${BIRD_REGION}.platform.bird.com"
BIRD_EMAIL=you@example.com

Le répertoire privé contient la réponse de vérification et les identifiants. Gardez ces fichiers hors du contrôle de version, des transcriptions de conversation et des journaux partagés.

1. Demander un code de connexion

Exemple de code

jq -n --arg email "$BIRD_EMAIL" '{email: $email}' |
  curl --fail-with-body --silent --show-error \
    "$BIRD_BASE_URL/v1/auth/magic-link" \
    -H 'Content-Type: application/json' --data-binary @-

Une requête réussie renvoie 204 sans corps. Lisez le code à six chiffres dans l'e-mail ; il expire après 15 minutes. La réponse ne révèle pas si le compte existe déjà.

2. Vérifier l'adresse e-mail

Remplacez 123456 par le code reçu par e-mail. Enregistrez la réponse sans afficher son ticket d'intégration :

Exemple de code

BIRD_CODE=123456
jq -n --arg email "$BIRD_EMAIL" --arg code "$BIRD_CODE" \
  '{email: $email, code: $code}' |
  curl --fail-with-body --silent --show-error \
    "$BIRD_BASE_URL/v1/auth/magic-link/verify-code" \
    -H 'Content-Type: application/json' --data-binary @- \
    --output "$BIRD_SIGNUP_DIR/verified.json"
jq -e '.onboarding_ticket | type == "string" and length > 0' \
  "$BIRD_SIGNUP_DIR/verified.json" > /dev/null

Ne continuez que si la vérification réussit et que la vérification du ticket se termine avec succès. Un nouveau compte vérifié reçoit un onboarding_ticket à usage unique. Un compte existant avec une organisation n'a pas besoin de ce flux d'inscription ; si la vérification exige la MFA, suivez plutôt le flux de connexion du compte existant.

3. Créer l'organisation et l'espace de travail

Choisissez les noms de votre organisation et de votre espace de travail, en gardant region aligné avec BIRD_BASE_URL. Cette requête utilise le ticket, aucun cookie jar ni jeton bearer n'est donc nécessaire :

Exemple de code

jq -n --arg region "$BIRD_REGION" \
  --slurpfile verified "$BIRD_SIGNUP_DIR/verified.json" \
  '{org_name: "Acme", workspace_name: "Production", region: $region,
    onboarding_ticket: $verified[0].onboarding_ticket}' |
  curl --fail-with-body --silent --show-error \
    "$BIRD_BASE_URL/v1/auth/onboarding" \
    -H 'Content-Type: application/json' --data-binary @- \
    --output "$BIRD_SIGNUP_DIR/account.json"

Une réponse réussie est 201 et contient organization, workspace, access_token, token_type et expires_in, plus un jeton de rafraîchissement lorsqu'il est émis. Le jeton d'accès expire après le nombre de secondes indiqué dans expires_in. Stockez la réponse de manière sécurisée. Il s'agit d'une configuration de compte unique ; un compte qui possède déjà une organisation reçoit 409.

4. Effectuer une requête authentifiée

Écrivez l'en-tête bearer dans un fichier de configuration curl privé, puis lisez l'identité associée à l'identifiant :

Exemple de code

jq -er '.access_token | select(type == "string" and length > 0) |
  "header = \"Authorization: Bearer \(.)\""' \
  "$BIRD_SIGNUP_DIR/account.json" > "$BIRD_SIGNUP_DIR/curl-auth.conf"
curl --fail-with-body --silent --show-error \
  --config "$BIRD_SIGNUP_DIR/curl-auth.conf" "$BIRD_BASE_URL/v1/auth/me"

Une réponse d'identité 200 confirme que l'identifiant fonctionne. Utilisez le même en-tête bearer et le même hôte régional pour les appels API suivants. Curl n'installe pas les identifiants dans le CLI ni dans un client MCP ; déplacez les identifiants enregistrés dans le magasin de secrets de votre application avant de supprimer le répertoire temporaire.

Étapes suivantes

CLI pour les agents est le contrat de commandes que l'identifiant généré déverrouille.
Le serveur MCP connecte le MCP stdio local après l'inscription CLI, ou le MCP hébergé via OAuth.
Envoyer votre premier e-mail est le parcours standard une fois le compte créé.

Poursuivez avec la documentation, les guides et les exemples sur ce sujet.

Obtenir un guide d'implémentation

Ressources associées