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:
| Scope | Arti write | admin | developer | analyst |
|---|---|---|---|---|
| workspace | Mengedit pengaturan workspace (nama, notifikasi) | write | read | read |
| api_keys | Membuat dan mencabut kunci API | write | write | none |
| emails | Mengirim email | write | write | read |
| email_management | Mengelola supresi dan konfigurasi email | write | write | read |
| email_marketing | Mengelola kontak, audiens, dan broadcast | write | write | read |
| domains | Menambah, memverifikasi, dan menghapus domain pengirim | write | write | read |
| webhooks | Mengonfigurasi endpoint webhook | write | write | read |
| sms | Mengirim SMS | write | write | read |
| sms_management | Mengelola pengirim, supresi, dan pengaturan SMS | write | write | read |
| verify | Mengirim dan memeriksa kode verifikasi | write | write | read |
| verify_management | Mengonfigurasi pengirim dan negara verifikasi | write | write | read |
| Mengirim pesan WhatsApp | write | read | read | |
| whatsapp_management | Mengelola template dan pengaturan WhatsApp | write | write | read |
| assets | Mengunggah, memperbarui, dan menghapus aset dan folder | write | write | read |
| compliance | Mengelola identitas registrasi, pengajuan, dan bukti | write | write | read |
| lookup | Mencari nomor telepon, alamat email, dan kecocokan identitas | write | write | none |
| mailbox | Mengirim dan membalas pesan kotak masuk | write | write | read |
| mailbox_management | Membuat, memperbarui, dan menghapus kotak masuk dan aturan penerimaan | write | write | read |
| realtime | Membuat aplikasi dan mempublikasikan event | write | write | read |
| voice | Membaca log leg dan statistik, serta melakukan panggilan | write | write | read |
| voice_management | Mengelola trunk, gateway, nomor, caller ID, dan tujuan | write | write | read |
| ip_pools | Melihat IP pool organisasi (hanya-baca) | read | read | read |
| members | Mengelola tim workspace dan undangan | write | read | read |
| analytics | Melihat laporan dan analitik keterkiriman | read | none | read |
| audit | Melihat log audit | read | none | read |
| request_logs | Melihat log permintaan (hanya-baca) | read | read | read |
Dalam praktiknya, admin menjalankan workspace, termasuk tim dan pengaturan. Developer dapat membangun integrasi, mengelola domain dan webhook, serta membuat kunci API. Analyst memiliki akses hanya baca.
Dua baris perlu diperhatikan lebih lanjut. ip_pools bersifat hanya baca bahkan untuk admin karena pembelian IP khusus dan pengelolaan pool memerlukan scope org:ip_pools:write di tingkat organisasi. Izin WhatsApp juga memisahkan pengelolaan dari pengiriman pesan. Developer dapat mengelola templat dan pengaturan dengan whatsapp_management:write, tetapi hanya dapat membaca pesan dengan whatsapp:read; pengiriman tetap dibatasi untuk admin. Produk lain menambahkan scope menggunakan model {scope, level} 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. Dua 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.
- 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).
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.
Seorang owner dapat mengundang owner atau billing_admin lain. Undangan tersebut memerlukan org:members:write, yang hanya dimiliki oleh 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
- Autentikasi & kunci API: scope untuk layanan, dan siapa yang dapat mengelola kunci
- Workspace: workspace tempat peran-peran ini melekat
- Billing & penggunaan: apa yang dikelola peran billing tingkat organisasi
Sumber daya terkait
Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.