Pendaftaran mandiri

Sebagian besar agen berjalan menggunakan akun yang sudah Anda miliki: Anda menyiapkan agen dan agen tersebut masuk melalui browser. Panduan ini membahas jalur lain, di mana agen yang belum memiliki akun membuat akun sendiri sepenuhnya dari terminal. Gunakan CLI atau curl untuk memverifikasi alamat email dan membuat organisasi, workspace, serta kredensial. MCP stdio lokal memerlukan kredensial tersimpan sebelum dapat dimulai; MCP yang di-host tidak menyediakan alat pendaftaran. Anda memerlukan akses ke kotak masuk email untuk mengambil kode verifikasi. Pendaftaran melalui Bird CLI atau server MCP diatribusikan ke alat yang membuatnya.

Gunakan CLI

Untuk perintah CLI di bawah, Anda perlu menginstal bird CLI. Pendaftaran dan verifikasi bersifat region-agnostic dan tidak memerlukan konfigurasi awal. Pada langkah terakhir, berikan --region (us1 atau eu1) ke create-org untuk memilih tempat akun dan datanya disimpan. Tidak diperlukan hostname atau variabel lingkungan.

1. Minta kode masuk

bird auth signup mengirim kode masuk enam digit melalui email. Memverifikasi kode tersebut akan membuat akun jika alamat email belum terdaftar. Proses ini menggunakan jalur magic-link tanpa kata sandi yang sama seperti dashboard, jadi kode yang dikirim via email adalah satu-satunya yang Anda butuhkan. Simpan alamat email untuk langkah berikutnya.

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

2. Verifikasi email

Kode enam digit dikirim melalui email, jadi kode tersebut berasal dari luar CLI: baca dari kotak masuk. Berikan kode beserta email yang sama ke bird auth verify-email, yang memasukkan Anda dan, untuk akun baru, mengembalikan onboarding_ticket sekali pakai.

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

3. Buat organisasi

bird auth create-org menggunakan tiket untuk membuat organisasi dan workspace Anda, lalu menyimpan kredensial yang dicetak sehingga CLI dan server MCP stdio lokal melakukan autentikasi sebagai akun baru mulai saat ini. Proses ini sekali pakai: panggilan kedua mengembalikan 409. --region memilih tempat akun dan datanya disimpan (us1 atau eu1) dan mengarahkan panggilan ke region tersebut; CLI menurunkan host dari nilai itu, jadi Anda tidak perlu mengatur URL.

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

Konfirmasi kredensial berfungsi:

bird auth status   # authenticated: true, valid: true

Akun sudah aktif dan terautentikasi. Agen sekarang dapat menggunakan CLI untuk mengonfigurasi channel dan mengirim pesan.

Periksa input CLI sebelum menjalankan

Setiap langkah bersifat self-describing dan tidak memerlukan kredensial, sehingga agen dapat merencanakan seluruh alur sebelum mengirim apa pun. bird auth --help mencetak alur berurutan, --example mencetak body permintaan siap edit, dan --response-schema mencetak field yang dikembalikan setiap perintah.

Gunakan curl

Anda memerlukan curl dan jq, tetapi tidak memerlukan Bird CLI, koneksi MCP, kunci API, atau sesi browser. Jalankan perintah di shell yang sama, hentikan jika permintaan gagal. Pilih us1 atau eu1 sebelum memulai; permintaan pembuatan organisasi harus dikirim ke host yang sesuai dengan region-nya.

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

Direktori privat menyimpan respons verifikasi dan kredensial. Jauhkan file-file ini dari source control, transkrip percakapan, dan log bersama.

1. Minta kode masuk

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

Permintaan yang berhasil mengembalikan 204 tanpa body. Baca kode enam digit dari email; kode kedaluwarsa setelah 15 menit. Respons tidak mengungkapkan apakah akun sudah ada.

2. Verifikasi email

Ganti 123456 dengan kode yang dikirim via email. Simpan respons tanpa mencetak tiket onboarding-nya:

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

Lanjutkan hanya jika verifikasi berhasil dan pemeriksaan tiket keluar dengan sukses. Akun baru yang terverifikasi menerima onboarding_ticket sekali pakai. Akun yang sudah memiliki organisasi tidak memerlukan alur pendaftaran ini; jika verifikasi memerlukan MFA, selesaikan alur masuk akun yang sudah ada.

3. Buat organisasi dan workspace

Pilih nama organisasi dan workspace Anda, pastikan region selaras dengan BIRD_BASE_URL. Permintaan ini menggunakan tiket, jadi tidak diperlukan cookie jar atau 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"

Respons yang berhasil adalah 201 dan berisi organization, workspace, access_token, token_type, dan expires_in, ditambah refresh token jika diterbitkan. Access token kedaluwarsa setelah jumlah detik di expires_in. Simpan respons dengan aman. Ini adalah pengaturan akun sekali pakai; akun yang sudah memiliki organisasi menerima 409.

4. Buat permintaan terautentikasi

Tulis bearer header ke file konfigurasi curl privat, lalu baca identitas di balik kredensial:

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"

Respons identitas 200 mengonfirmasi bahwa kredensial berfungsi. Gunakan bearer header dan host regional yang sama untuk panggilan API berikutnya. Curl tidak menginstal kredensial ke CLI atau klien MCP; pindahkan kredensial tersimpan ke secret store aplikasi Anda sebelum menghapus direktori sementara.

Langkah berikutnya

• CLI untuk agen adalah kontrak perintah yang sekarang dapat dibuka oleh kredensial yang dicetak.
• Server MCP menghubungkan MCP stdio lokal setelah pendaftaran CLI, atau MCP yang di-host melalui OAuth.
• Kirim email pertama Anda adalah jalur utama setelah akun dibuat.