Sign inGet Started

Pengguna, tim & peran

Akses untuk orang di Bird berbasis peran: pengguna memegang satu peran pada workspace Anda, dan setiap peran adalah sekumpulan izin yang tetap. Tidak ada yang perlu dikonfigurasi lagi; pilih peran yang tepat dan izinnya mengikuti.

Peran mengatur apa yang dapat dilakukan orang di dashboard. Apa yang dapat dilakukan layanan diatur oleh scope kunci API: kosakata izin yang sama, diberikan per kunci, bukan per peran.

Peran workspace

Peran yang Anda gunakan sehari-hari berada di workspace (lihat Workspace): admin, developer, dan analyst. Kelola di dashboard pada Settings > Team.

Setiap izin adalah pasangan {scope, level}, dengan level berupa read atau write (write mencakup read). Peran adalah sekumpulan pasangan ini yang diberi nama dan bersifat tetap:

ScopeArti writeadmindeveloperanalyst
workspaceMengedit pengaturan workspace (nama, notifikasi)writereadread
access_restrictionsMengelola daftar IP yang diizinkan untuk workspacewritenonenone
api_keysMembuat dan mencabut kunci APIwritewritenone
service_accountsMeninjau dan mencabut integrasi platform yang terhubungwritewritenone
emailsMengirim emailwritewriteread
email_managementMengelola supresi dan konfigurasi emailwritewriteread
email_marketingMengelola kontak, audiens, dan broadcastwritewriteread
inbox_insightsMengonfigurasi Inbox Insights dan melihat data penempatanwritewriteread
competitiveMengelola watchlist Competitive Insightswritenoneread
domainsMenambah, memverifikasi, dan menghapus domain pengirimwritewriteread
webhooksMengonfigurasi endpoint webhookwritewriteread
smsMengirim SMSwritewriteread
sms_managementMengelola pengirim, supresi, dan pengaturan SMSwritewriteread
verifyMengirim dan memeriksa kode verifikasiwritewriteread
verify_managementMengonfigurasi pengirim dan negara verifikasiwritewriteread
whatsappMengirim pesan WhatsAppwritewriteread
whatsapp_managementMengelola template dan pengaturan WhatsAppwritewriteread
ambMengirim Apple Messages for Businesswritewriteread
amb_managementMengelola catatan bisnis, aturan perutean, dan supresi Apple Messageswritewriteread
assetsMengunggah, memperbarui, dan menghapus aset dan folderwritewriteread
automationsMembuat, memublikasikan, dan menjalankan automasi workspacewritewriteread
complianceMengelola identitas registrasi, pengajuan, dan buktiwritewriteread
esimMembuat pesanan eSIM dan mengelola eSIMwritewriteread
esim_credentialsMelihat dan mengelola kredensial instalasi eSIMwritewritenone
lookupMencari nomor telepon, alamat email, dan kecocokan identitaswritewritenone
mailboxMengirim dan membalas pesan kotak masukwritewriteread
mailbox_managementMembuat, memperbarui, dan menghapus kotak masuk dan aturan penerimaanwritewriteread
numbersMencari, membeli, mengonfigurasi, dan melepas nomor teleponwritewriteread
preferencesMencatat dan menghapus preferensi pesan lintas kanalwritewriteread
realtimeMembuat aplikasi dan mempublikasikan eventwritewriteread
voiceMembaca log leg dan statistik, serta melakukan panggilanwritewriteread
voice_managementMengelola trunk, gateway, nomor, caller ID, dan tujuanwritewriteread
ip_poolsMelihat IP pool organisasi (hanya-baca)readreadread
trustMelihat persyaratan kepercayaan organisasi (hanya-baca)readreadread
membersMengelola tim workspace dan undanganwritereadread
analyticsMelihat laporan dan analitik keterkirimanreadnoneread
auditMelihat log auditreadnoneread
request_logsMelihat log permintaan (hanya-baca)readreadread

Dalam praktiknya, admin menjalankan workspace, termasuk tim, daftar izin IP, dan pengaturan. Developer dapat membangun integrasi di berbagai kanal, mengelola domain dan webhook, serta membuat kunci API. Analyst memiliki akses hanya baca (dan tidak memiliki akses ke scope khusus tulis yang membelanjakan saldo wallet seperti lookup atau scope yang memuat rahasia seperti esim_credentials).

Dua baris hanya baca perlu diperhatikan lebih lanjut: ip_pools dan trust bersifat hanya baca di tingkat workspace, bahkan untuk admin, karena pembelian IP khusus (org:ip_pools:write) dan dimulainya verifikasi kepercayaan organisasi (org:trust:write) adalah operasi tingkat organisasi. Scope kanal memisahkan lalu lintas (emails, sms, whatsapp, amb, voice) dari konfigurasi kanal (email_management, sms_management, whatsapp_management, amb_management, voice_management). Dengan begitu, scope kunci API dapat dibatasi secara sempit, meskipun peran workspace memberikan keduanya pada tingkat yang sama.

403 dari endpoint mana pun berarti prinsipal yang terautentikasi tidak memiliki {scope, level} yang diperlukan endpoint tersebut. Solusinya adalah perubahan peran (untuk orang) atau kunci baru dengan scope yang tepat (untuk layanan).

Peran organisasi

Di balik workspace Anda terdapat organisasi yang memiliki billing dan daftar anggota keseluruhan. Tiga peran mengelola lapisan tersebut:

  • owner: semuanya. Akses baca dan tulis penuh di seluruh operasi organisasi dan workspace. Sebuah organisasi dapat (dan sebaiknya) memiliki beberapa owner. Orang yang membuat akun memulai sebagai owner.
  • org_admin: administrasi organisasi (org:workspaces:write, org:master_keys:write, org:members:write, org:settings:write, org:access_restrictions:write, org:ip_pools:write, dan org:audit:read), ditambah akses admin otomatis di setiap workspace organisasi tersebut.
  • billing_admin: billing dan pengaturan organisasi (org:billing:write, org:settings:write) ditambah akses baca ke daftar anggota organisasi dan metadata workspace. Tidak ada akses ke sumber daya di dalam workspace.

Peran ini jarang dibutuhkan sehari-hari: sebagian besar rekan tim hanya memerlukan peran workspace.

Anggota dan tim

Keanggotaan bersifat implisit: pengguna "in" organisasi Anda jika mereka memegang peran organisasi atau peran workspace. Tidak ada catatan keanggotaan terpisah yang perlu dikelola.

Anda mengelola orang di workspace Anda melalui dashboard pada Settings > Team, yang dijaga oleh scope workspace members; admin workspace mengelola tim di sini tanpa peran tingkat organisasi apa pun. Pengelolaan tim adalah sesuatu yang dilakukan orang, jadi kunci API tidak dapat memegang scope members (lihat Autentikasi).

Pengaturan Team workspace di dashboard Bird, menampilkan daftar anggota beserta peran mereka dan aksi undang-anggota

Menghapus akses workspace seseorang akan menghapus peran tersebut tanpa mengubah peran organisasi yang mereka miliki. Menghapus seseorang dari organisasi akan mencabut seluruh akses akun mereka. Kunci API yang mereka buat tetap berfungsi karena setiap kunci milik workspace secara independen dari pembuatnya.

Undangan

Dari Settings > Team, undang alamat email dengan sebuah peran, dan Bird mengurus sisanya. Di balik tombol tersebut adalah smart invitation: satu alur menangani kolega yang sudah menjadi anggota organisasi Anda maupun orang yang belum pernah mengenal Bird.

  • Sudah menjadi anggota organisasi: mereka langsung ditambahkan ke workspace dengan peran yang diberikan. Tidak ada email, tidak perlu menunggu; responsnya adalah objek member.
  • Belum menjadi anggota: Bird membuat undangan, mengirim email berisi tautan pendaftaran, dan responsnya adalah objek invitation dengan status pending. Tautan berlaku selama 7 hari; setelah itu undangan kedaluwarsa dan Anda mengundang mereka kembali.

Field type pada respons (team_member atau invitation) memberi tahu Anda mana yang terjadi. Undangan tertunda kedua untuk email yang sama mengembalikan 409 alih-alih membuat duplikat, dan Anda dapat menarik undangan tertunda kapan saja dari halaman yang sama.

owner atau org_admin dapat mengundang peran tingkat organisasi (org:members:write). Hanya owner yang dapat memberikan peran owner.

Pagar pengaman

Dua invarian diberlakukan pada setiap perubahan peran, terlepas dari siapa yang meminta:

  • Owner terakhir tidak dapat dipindahkan. Menurunkan atau menghapus satu-satunya owner organisasi mengembalikan 409: organisasi tidak boleh berakhir tanpa owner. Promosikan owner kedua terlebih dahulu.
  • Anda tidak dapat mengubah akses Anda sendiri. Mengubah peran sendiri atau menghapus diri sendiri mengembalikan 403. Ini mencegah penguncian diri secara tidak sengaja maupun promosi diri secara diam-diam; admin atau owner lain yang harus melakukan perubahan.

Cara konteks dipilih

Endpoint anggota dan tim tersedia di dua tingkat, dan organisasi atau workspace mana yang menjadi target permintaan bergantung pada cara autentikasinya:

  • Session auth (dashboard, atau alat yang bertindak sebagai Anda) menyediakan konteks per permintaan: X-Organization-Id pada endpoint berskope organisasi, X-Workspace-Id pada yang berskope workspace.
  • Kunci API membawa konteksnya secara implisit. Kunci milik workspace Anda, yang juga menentukan organisasinya; tidak perlu header, dan header konteks yang bertentangan dengan kunci ditolak karena tidak valid (400).

Lihat Workspace untuk model resolusi konteks lengkap.

Langkah selanjutnya

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini.