Akses dengan cakupan izin yang tetap Anda kendalikan

Koneksi merupakan token ruang kerja

Pemilik dan admin ruang kerja membuat koneksi di halaman Pengembang. Setiap koneksi merupakan token bearer yang terikat pada satu ruang kerja dan satu audiens: token rest (sw_rest_...) hanya berfungsi untuk /api/v1, dan token mcp (sw_mcp_...) hanya berfungsi untuk /mcp.

Kirim token dalam header Authorization. Jangan pernah meletakkannya dalam URL, string kueri, berkas impor, atau bundel peramban.

Authorization: Bearer sw_rest_...

Cakupan mempersempit izin peran Anda

Koneksi baru dimulai dengan bawaan hanya baca: workspaces:read, catalog:read, dan worlds:read. Tambahkan hanya yang dibutuhkan tugas, misalnya worlds:write untuk menyunting draf atau worlds:publish untuk menerbitkan. GET /me memerlukan account:read.

Cakupan tidak pernah memberi kemampuan melebihi kemampuan pembuat token, dan peran tersebut dibaca kembali pada setiap permintaan. Id dari ruang kerja lain menjawab 404, sehingga token tidak dapat menemukan sesuatu yang tidak boleh dilihat.

Cakupan sensitif harus dipilih secara tegas

Cakupan yang menjangkau alamat pelanggan, pesan pengunjung, penagihan, penghapusan, penulisan DNS, pembelanjaan, perubahan tim, atau webhook tidak pernah dicentang sebelumnya. Menambahkannya meminta Anda masuk ulang terlebih dahulu. Alat MCP terkait tetap tersembunyi hingga token memiliki cakupan tersebut.

Sebagian tindakan sama sekali tidak tersedia bagi token: memutuskan persetujuan, menghapus atau memulihkan casa dan akun (memerlukan masuk ulang langsung melalui aplikasi dan menjawab 403 reauthentication_required), serta ekspor data.

Kedaluwarsa, rotasi, dan pencabutan

• Token secara bawaan kedaluwarsa setelah 30 hari dan paling lama setelah 90 hari.
• Hanya hash yang disimpan, sehingga token yang hilang tidak dapat ditampilkan kembali. Buat koneksi baru sebagai gantinya.
• Untuk merotasi, buat koneksi baru, alihkan klien ke koneksi tersebut, lalu cabut yang lama. Pencabutan berlaku pada permintaan berikutnya, termasuk pekerjaan yang sudah diantrekan agen.

Kesalahan yang mungkin diterima

• 401: token tidak tersedia, tidak dikenal, kedaluwarsa, dicabut, atau ditujukan untuk audiens lain.
• 403 insufficient_scope: token tidak memiliki suatu izin. context.required_scope menyebutkannya dan respons memuat header WWW-Authenticate.
• 404: sumber daya tidak ada dalam ruang kerja token ini.

OAuth belum tersedia

Klien agen yang hanya mendukung masuk melalui OAuth belum dapat terhubung. Karena itulah /.well-known/oauth-protected-resource/mcp tidak mencantumkan server otorisasi. Sebagai gantinya, gunakan token koneksi dalam pengaturan header klien.