Self-Service-Registrierung

Die meisten Agenten arbeiten mit einem Konto, das Sie bereits besitzen: Sie richten Ihren Agenten ein und er meldet sich über den Browser an. Diese Anleitung beschreibt den anderen Weg, bei dem ein Agent ohne Konto sich selbst eines erstellt, vollständig aus dem Terminal. Verwenden Sie die CLI oder curl, um eine E-Mail-Adresse zu verifizieren und eine Organisation, einen Workspace und ein Credential zu erstellen. Lokales stdio MCP benötigt ein gespeichertes Credential, bevor es starten kann; gehostetes MCP stellt keine Signup-Tools bereit. Sie benötigen Zugriff auf das E-Mail-Postfach, um den Bestätigungscode abzurufen. Signups über den Bird CLI oder MCP-Server werden dem Tool zugeordnet, das sie ausgelöst hat.

Die CLI verwenden

Für die folgenden CLI-Befehle benötigen Sie die installierte bird CLI. Registrierung und Verifizierung sind regionsunabhängig und erfordern keine Erstkonfiguration. Übergeben Sie im letzten Schritt --region (us1 oder eu1) an create-org, um festzulegen, wo das Konto und seine Daten gespeichert werden. Hostnamen oder Umgebungsvariablen sind nicht erforderlich.

1. Anmeldecode anfordern

bird auth signup sendet einen sechsstelligen Anmeldecode per E-Mail. Das Verifizieren dieses Codes erstellt das Konto, falls die E-Mail-Adresse neu ist. Der Vorgang nutzt denselben passwortlosen Magic-Link-Pfad wie das Dashboard – der per E-Mail gesendete Code ist alles, was Sie brauchen. Behalten Sie die E-Mail-Adresse für den nächsten Schritt.

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

2. E-Mail verifizieren

Der sechsstellige Code kommt per E-Mail und stammt daher von außerhalb der CLI: Lesen Sie ihn aus dem Postfach. Übergeben Sie ihn zusammen mit derselben E-Mail-Adresse an bird auth verify-email. Dieser Befehl meldet Sie an und gibt bei einem brandneuen Konto ein einmalig verwendbares onboarding_ticket zurück.

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

3. Organisation erstellen

bird auth create-org löst das Ticket ein, um Ihre Organisation und Ihren Workspace zu erstellen, und speichert dann das erzeugte Credential, sodass sich die CLI und der lokale stdio-MCP-Server ab diesem Zeitpunkt als das neue Konto authentifizieren. Der Aufruf ist einmalig: Ein zweiter Aufruf gibt 409 zurück. --region legt fest, wo das Konto und seine Daten gespeichert werden (us1 oder eu1), und leitet den Aufruf an die entsprechende Region weiter; die CLI leitet den Host daraus ab, sodass Sie keine URL setzen müssen.

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

Prüfen Sie, ob das Credential funktioniert:

bird auth status   # authenticated: true, valid: true

Das Konto ist aktiv und authentifiziert. Der Agent kann jetzt die CLI verwenden, um Kanäle zu konfigurieren und Nachrichten zu senden.

CLI-Eingaben vor der Ausführung prüfen

Jeder Schritt ist selbstbeschreibend und erfordert kein Credential, sodass ein Agent die gesamte Kette planen kann, bevor er etwas sendet. bird auth --help gibt den geordneten Ablauf aus, --example gibt einen bearbeitungsfertigen Request-Body aus, und --response-schema gibt die Felder aus, die jeder Befehl zurückgibt.

curl verwenden

Sie benötigen curl und jq, aber keine Bird CLI, MCP-Verbindung, keinen API-Key und keine Browsersitzung. Führen Sie die Befehle in derselben Shell aus und brechen Sie ab, wenn ein Request fehlschlägt. Wählen Sie vor dem Start us1 oder eu1; der Request zur Organisationserstellung muss an den Host gesendet werden, der zu seinem region passt.

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

Das private Verzeichnis enthält die Verifizierungsantwort und die Credentials. Halten Sie diese Dateien aus der Versionskontrolle, Chat-Protokollen und gemeinsam genutzten Logs heraus.

1. Anmeldecode anfordern

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 @-

Ein erfolgreicher Request gibt 204 ohne Body zurück. Lesen Sie den sechsstelligen Code aus der E-Mail; er läuft nach 15 Minuten ab. Die Antwort verrät nicht, ob das Konto bereits existiert.

2. E-Mail verifizieren

Ersetzen Sie 123456 durch den per E-Mail erhaltenen Code. Speichern Sie die Antwort, ohne das Onboarding-Ticket auszugeben:

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

Fahren Sie nur fort, wenn die Verifizierung erfolgreich ist und die Ticket-Prüfung erfolgreich beendet wird. Ein neu verifiziertes Konto erhält ein einmalig verwendbares onboarding_ticket. Ein bestehendes Konto mit einer Organisation benötigt diesen Registrierungsablauf nicht; falls die Verifizierung MFA erfordert, durchlaufen Sie stattdessen den Anmeldeablauf des bestehenden Kontos.

3. Organisation und Workspace erstellen

Wählen Sie Ihre Organisations- und Workspace-Namen und halten Sie region mit BIRD_BASE_URL konsistent. Dieser Request verwendet das Ticket, sodass weder ein Cookie-Jar noch ein Bearer-Token erforderlich ist:

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"

Eine erfolgreiche Antwort ist 201 und enthält organization, workspace, access_token, token_type und expires_in sowie ein Refresh-Token, falls eines ausgestellt wird. Das Access-Token läuft nach der in expires_in angegebenen Anzahl von Sekunden ab. Speichern Sie die Antwort sicher. Dies ist eine einmalige Kontoeinrichtung; ein Konto, das bereits eine Organisation besitzt, erhält 409.

4. Authentifizierten Request senden

Schreiben Sie den Bearer-Header in eine private curl-Konfigurationsdatei und lesen Sie dann die Identität hinter dem Credential aus:

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"

Eine 200-Identitätsantwort bestätigt, dass das Credential funktioniert. Verwenden Sie denselben Bearer-Header und regionalen Host für nachfolgende API-Aufrufe. Curl installiert Credentials nicht in der CLI oder einem MCP-Client; verschieben Sie die gespeicherten Credentials in den Secret-Store Ihrer Anwendung, bevor Sie das temporäre Verzeichnis löschen.

Nächste Schritte

• CLI für Agents ist der Befehlsvertrag, den das erzeugte Credential nun freischaltet.
• MCP-Server verbindet lokale stdio-MCP nach der CLI-Registrierung oder gehostete MCP über OAuth.
• Erste E-Mail senden ist der Standardpfad, sobald das Konto existiert.