Registrazione self-service

La maggior parte degli agenti opera su un account già esistente: configuri il tuo agente e questo accede tramite il browser. Questa guida segue l'altro percorso, in cui un agente privo di account ne crea uno autonomamente, interamente dal terminale. Usa CLI o curl per verificare un indirizzo email e creare un'organizzazione, uno spazio di lavoro e una credenziale. MCP stdio locale richiede una credenziale salvata prima di poter avviarsi; MCP in hosting non espone strumenti di registrazione. È necessario l'accesso alla casella email per recuperare il codice di verifica. Le registrazioni tramite Bird CLI o il server MCP sono attribuite allo strumento che le ha effettuate.

Usare la CLI

Per i comandi CLI seguenti, devi avere la bird CLI installata. Registrazione e verifica sono indipendenti dalla regione e non richiedono configurazione iniziale. All'ultimo passaggio, passa --region (us1 o eu1) a create-org per scegliere dove risiedono l'account e i relativi dati. Non servono hostname né variabili d'ambiente.

1. Richiedere un codice di accesso

bird auth signup invia per email un codice di accesso a sei cifre. La verifica del codice crea l'account se l'indirizzo email è nuovo. Usa lo stesso percorso passwordless magic-link della dashboard, quindi il codice ricevuto via email è tutto ciò che serve. Conserva l'indirizzo email per il passaggio successivo.

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

2. Verificare l'email

Il codice a sei cifre arriva per email, quindi proviene dall'esterno della CLI: leggilo dalla casella di posta. Passalo insieme alla stessa email a bird auth verify-email, che esegue l'accesso e, per un account nuovo, restituisce un onboarding_ticket monouso.

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

3. Creare l'organizzazione

bird auth create-org consuma il ticket per creare l'organizzazione e lo spazio di lavoro, poi salva la credenziale generata in modo che la CLI e il server stdio locale MCP si autentichino come il nuovo account da questo momento in poi. L'operazione è una tantum: una seconda chiamata restituisce 409. --region sceglie dove risiedono l'account e i relativi dati (us1 o eu1) e instrada la chiamata verso quella regione; la CLI ricava l'host da quel valore, quindi non devi impostare un URL.

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

Verifica che la credenziale funzioni:

bird auth status   # authenticated: true, valid: true

L'account è attivo e autenticato. L'agent può ora usare la CLI per configurare canali e inviare messaggi.

Ispezionare gli input di CLI prima dell'esecuzione

Ogni passaggio è autodescrittivo e non richiede credenziali, quindi un agent può pianificare l'intera catena prima di inviare qualsiasi cosa. bird auth --help stampa il flusso ordinato, --example stampa un corpo della richiesta pronto da modificare, e --response-schema stampa i campi restituiti da ciascun comando.

Usare curl

Servono curl e jq, ma non Bird CLI, connessione MCP, chiave API né sessione browser. Esegui i comandi nella stessa shell, fermandoti se una richiesta fallisce. Scegli us1 o eu1 prima di iniziare; la richiesta di creazione dell'organizzazione deve essere indirizzata all'host corrispondente al suo region.

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

La directory privata contiene la risposta di verifica e le credenziali. Tieni questi file fuori dal controllo di versione, dalle trascrizioni di chat e dai log condivisi.

1. Richiedere un codice di accesso

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

Una richiesta riuscita restituisce 204 senza corpo. Leggi il codice a sei cifre dall'email; scade dopo 15 minuti. La risposta non rivela se l'account esiste già.

2. Verificare l'email

Sostituisci 123456 con il codice ricevuto via email. Salva la risposta senza stampare il relativo onboarding ticket:

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

Prosegui solo se la verifica ha successo e il controllo del ticket termina correttamente. Un nuovo account verificato riceve un onboarding_ticket monouso. Un account esistente che ha già un'organizzazione non ha bisogno di questo flusso di registrazione; se la verifica richiede MFA, completa invece il flusso di accesso dell'account esistente.

3. Creare l'organizzazione e lo spazio di lavoro

Scegli i nomi dell'organizzazione e dello spazio di lavoro, mantenendo region allineato con BIRD_BASE_URL. Questa richiesta usa il ticket, quindi non servono cookie jar né bearer token:

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"

Una risposta riuscita è 201 e contiene organization, workspace, access_token, token_type e expires_in, più un refresh token quando emesso. L'access token scade dopo il numero di secondi indicato in expires_in. Salva la risposta in modo sicuro. Questa è una configurazione una tantum dell'account; un account che ha già un'organizzazione riceve 409.

4. Effettuare una richiesta autenticata

Scrivi l'header bearer in un file di configurazione curl privato, poi leggi l'identità associata alla credenziale:

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"

Una risposta identity 200 conferma che la credenziale funziona. Usa lo stesso header bearer e lo stesso host regionale per le chiamate API successive. Curl non installa le credenziali nella CLI né in un client MCP; sposta le credenziali salvate nel secret store della tua applicazione prima di rimuovere la directory temporanea.

Passaggi successivi

• CLI per agent è il contratto di comandi che la credenziale generata ora sblocca.
• Server MCP connette lo stdio locale MCP dopo la registrazione CLI, oppure l'hosted MCP tramite OAuth.
• Invia la tua prima email è il percorso principale una volta che l'account esiste.