Space Access Token

Space Access Token adalah token yang dapat membaca dan menulis konten di dalam satu Space. Dengan token ini Anda dapat membuat, mengubah, dan menghapus konten melalui CMA, dan pembacaan CDA serta Upload pun dipanggil dengan token ini. Saat diterbitkan, token diikat ke satu SpaceRole, dan peran itulah yang menentukan apa dan sampai sejauh mana token dapat bekerja (yaitu Content Type mana saja yang boleh ditangani dengan tindakan apa).

Berbeda dengan Delivery Access Token yang hanya-baca, token ini juga dapat menulis. Namun, berbeda dengan Personal Access Token yang terikat pada seluruh akun pengguna, token ini terbatas hanya pada satu Space dan tidak dapat mengakses pengaturan Space, organisasi, bidang akun, maupun Space lain. Di CMA, Space Access Token merupakan sumber daya turunan dari Space, dan path-nya mengacu pada /spaces/{spaceId}/space-access-tokens. Apakah token ini ditempatkan di server atau di klien yang terekspos (misalnya penulisan anonim) ditentukan sesuai layanan. Karena ini token kuat yang memiliki hak tulis, keamanan dijaga dengan mempersempit peran yang diikat sesuai cakupan keterpaparan tempat token itu berada (lihat Keamanan: pengikatan peran sesuai cakupan keterpaparan di bawah).

Struktur sumber daya

Berikut adalah respons saat sebuah Space Access Token dibuat. sys (properti sistem) memuat nilai token dan cakupannya, sedangkan body memuat name, description, dan allowedReferrers.

{
  "sys": {
    "id": "7WpR4mKq2bTnXfLc8Vd3HsJ9gEyAo",
    "type": "SpaceAccessToken",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "user": { "sys": { "id": "3trmXRLdJIqc9GPBbyFYQQwYT32LnU", "type": "Refer", "targetType": "User" } },
    "createdBy": { "sys": { "id": "9dLmQ2pVnRb8sTfWcXd3LhJ7gK", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-06-19T02:15:38.472Z",
    "updatedBy": { "sys": { "id": "9dLmQ2pVnRb8sTfWcXd3LhJ7gK", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-06-19T02:15:38.472Z",
    "accessToken": "SPCATq8Lm2vK9pXfR1Zt0Nc4Wd6Hg5Ua2Ee9Ck3PoYx8Bj6Hg5Ua2Ee9Ck3Po…",
    "scopes": ["SPACE_ACCESS_TOKEN"]
  },
  "allowedReferrers": [],
  "description": "Token server untuk pendaftaran dan penyuntingan produk toko pakaian",
  "name": "Server backend produk"
}

Kunci utama:

• sys.id: pengenal unik Space Access Token. Nilai ini masuk ke {spaceAccessTokenId} pada path baca, ubah, dan hapus tunggal.
• sys.space: Space tempat token ini berada. Token hanya bekerja pada satu Space ini saja.
• sys.accessToken: nilai token rahasia yang digunakan untuk memanggil API. Dimulai dengan SPCAT, dan karena nilai yang sama tetap muncul apa adanya pada pembacaan setelah penerbitan, berhati-hatilah terhadap keterpaparannya (lihat bagian keamanan di bawah).
• sys.scopes: cakupan hak token. Saat diterbitkan, Space Access Token selalu bernilai ["SPACE_ACCESS_TOKEN"].
• sys.user: pengguna khusus yang menjadi subjek hak dari token ini. Pengguna ini dibuat secara otomatis saat penerbitan, dan hak dari SpaceRole yang diikat diberikan kepada pengguna ini. Dengan kata lain, hak efektif token berasal dari pengguna ini. Pengguna ini berbeda dari orang yang benar-benar menerbitkan token ini (sys.createdBy).
• name: nama token yang ditetapkan saat pembuatan (contoh: Server backend produk).
• description: deskripsi token (opsional).
• allowedReferrers: daftar yang membatasi dari origin mana token ini boleh dipanggil. Jika daftar ini kosong, panggilan tidak dibatasi. Contoh di atas mengosongkan daftar karena token itu dipanggil dari server (untuk aturan penulisan dan cara pemeriksaan, lihat Aturan penulisan origin dan Pemeriksaan Referer).

role (SpaceRole yang akan diikat) adalah nilai input yang hanya dikirim melalui body permintaan pembuatan, dan tidak disertakan dalam sumber daya respons. Peran yang diikat diberikan dengan cara ditetapkan kepada pengguna khusus token ini (sys.user pada respons), sehingga tidak dikembalikan sebagai field role pada respons pembacaan. accessToken pada contoh di atas adalah nilai rahasia, sehingga diganti dengan string contoh. Nilai sebenarnya berupa string panjang dan tidak transparan yang dimulai dengan SPCAT, dan akan tetap sama ketika dibaca kembali setelah diterbitkan.

Properti sistem (sys)

Setiap Space Access Token memuat properti sistem umum dan properti khusus token di dalam objek sys. space, user, createdBy, dan updatedBy masuk dalam bentuk Refer ({ "sys": { "id", "type": "Refer", "targetType" } }).

Properti body:

Input khusus body permintaan pembuatan:

Keamanan: pengikatan peran sesuai cakupan keterpaparan

Space Access Token adalah token kuat yang juga dapat menulis. SpaceRole mana yang diikat menjadi batas kemampuan token ini sekaligus batas keamanannya. Apakah token ini ditempatkan di server atau di klien yang terekspos (misalnya penulisan anonim) ditentukan sesuai layanan, dan keamanan dijaga bukan dengan "di mana disembunyikan", melainkan dengan mempersempit peran yang diikat sesuai cakupan keterpaparan.

• Pada role di permintaan pembuatan, masukkan sys.id dari SpaceRole sempit yang hanya mengizinkan tindakan yang diperlukan untuk penggunaannya. Untuk token server pendaftaran produk, ikat peran yang hanya mengizinkan baca dan tulis pada Content Type produk; untuk token penulisan anonim yang terbuka, ikat peran yang hanya mengizinkan pembuatan (create) pada Content Type postingan. Dengan begitu, ikatkan seminimal mungkin sesuai cakupan keterpaparan.
• Semakin token itu terekspos ke klien publik, semakin sempit peran yang ditetapkan. Hanya izinkan sampai cakupan yang masih dapat ditanggung seandainya token itu bocor. Jangan mengikat peran Administrator atau peran tulis berjangkauan luas ke token publik. Selain itu, jangan asal memakai item pertama dari daftar SpaceRole; tentukan secara eksplisit sys.id dari peran sempit yang Anda maksud.
• Jika token dipanggil dari browser, persempit juga titik pemanggilan token itu dengan allowedReferrers. Peran yang diikat menentukan apa yang dapat dikerjakan dengan token ini, sedangkan daftar tersebut menentukan dari mana token ini dapat dipanggil (lihat Pemeriksaan Referer).
• Untuk pengiriman hanya-baca yang dibuka kepada pengunjung, Delivery Access Token yang tidak memiliki hak tulis lebih sesuai. Gunakan Space Access Token hanya saat tulis diperlukan, dan persempit perannya sesuai cakupan keterpaparan.
• accessToken adalah nilai rahasia yang dibaca dengan nilai yang sama bahkan setelah diterbitkan. Di tempat yang tidak perlu terekspos, jangan tinggalkan sebagai teks polos di kode, log, penyimpanan, atau pesan galat; jika keterpaparan dicurigai, hapus untuk membatalkannya lalu ganti dengan token baru.

Status dan batasan

Batasan nilai yang harus dipatuhi saat pembuatan dan pengubahan.

Aturan tentang pengikatan dan hak:

• role yang akan diikat harus benar-benar ada di Space tersebut. Jika Anda memasukkan sys.id peran yang tidak ada, pembuatan ditolak.
• Pemanggil hanya dapat mengikat peran yang ia miliki sendiri di Space tersebut. Ini adalah batasan untuk mencegah pemberian hak yang lebih tinggi ke token dengan mengikat peran yang tidak dimiliki pemanggil; permintaan pembuatan yang melanggar batasan itu ditolak. Namun, pengelola Space itu (pemegang peran Administrator) tidak terkena batasan ini dan dapat mengikat peran apa pun.
• Space Access Token adalah sumber daya yang memiliki batas jumlah. Jika batas jumlah penerbitan pada paket Anda saat ini terlampaui, pembuatan ditolak. Untuk batas per paket, lihat Paket Harga.
• Penerbitan dan pengelolaan (buat, baca, ubah, hapus) memerlukan SETTING_SPACE_ACCESS_TOKEN pada settings dari peran pemanggil. Ini adalah aksi yang terpisah dari SETTING_DELIVERY_ACCESS_TOKEN yang menerbitkan Delivery Access Token hanya-baca, sehingga Anda dapat memberikan izin penerbitan token pengiriman saja sambil tetap melarang penerbitan token ini (lihat SpaceRole).
• API ini hanya dapat dipanggil dengan sesi login konsol dan Personal Access Token. Space Access Token itu sendiri tidak dapat membuat Space Access Token lain, dan hal ini tetap berlaku meskipun Anda menaruh SETTING_SPACE_ACCESS_TOKEN pada peran yang diikat.

Aturan penulisan origin

Setiap item dalam allowedReferrers adalah string yang menunjuk satu origin yang diizinkan memanggil token ini. Tulis item itu dalam bentuk berikut.

"allowedReferrers": [
  "https://shop.example.com",
  "https://*.shop.example.com",
  "http://localhost:3000"
]

Daftar ini memuat paling banyak 50 item, dan Anda tidak boleh memasukkan origin yang sama dua kali. Setiap item harus mengikuti aturan berikut.

• Gunakan hanya https sebagai skema URL. http hanya diizinkan untuk localhost, 127.0.0.1, dan [::1].
• Gunakan wildcard hanya sebagai satu label *. di bagian paling depan. Pada path, wildcard tidak dapat dipakai.
• Tulis host dalam ASCII. Masukkan domain terinternasionalisasi dalam bentuk Punycode.
• Port berada dalam rentang 1 sampai 65535. Jika Anda menghilangkan port, port bawaan skema itu berlaku (443 untuk https, 80 untuk http).
• Jika Anda menuliskan path, permintaan hanya lolos ketika path permintaan itu sama persis. Browser mengirim path dengan percent-encoding, jadi gunakan hanya ASCII pada path.
• Item yang membawa informasi pengguna (user@), kueri (?), atau fragmen (#) ditolak.

Pemeriksaan ini berlaku pada ketiga jalur sekaligus: pembuatan, pengubahan penuh, dan pengubahan sebagian. Jika ada satu saja item yang melanggar aturan, daftar itu tidak disimpan dan permintaan ditolak, lalu satu item yang melanggar disebutkan pada alasan error (lihat Error).

Pemeriksaan Referer

Setelah token diterbitkan, setiap panggilan API dengan token ini diperiksa terhadap allowedReferrers untuk menentukan apakah panggilan itu lolos.

• Jika daftar ini kosong, tidak ada pembatasan yang diterapkan. Panggilan dari origin mana pun lolos.
• Jika daftar memuat setidaknya satu item, pemeriksaan memakai nilai header Referer pada permintaan. Header Origin tidak diperiksa.
• Permintaan tanpa header Referer, atau dengan header Referer bernilai kosong, ditolak. Untuk token yang akan dipakai di tempat yang tidak mengirim Referer, misalnya panggilan antarserver, kosongkan daftar ini.
• Agar lolos, skema, host, dan port pada Referer ketiganya harus sama dengan salah satu item pada daftar. Jika item itu memuat path, path pun harus sama.
• https://*.shop.example.com mencakup semua host yang berakhiran .shop.example.com, misalnya admin.shop.example.com, tetapi tidak mencakup shop.example.com itu sendiri. Untuk mengizinkan keduanya, tambahkan https://shop.example.com sebagai satu item lagi.
• Pemeriksaan ini berlaku pada setiap permintaan yang Anda kirim dengan token ini. Aturan itu sama, baik Anda memanggil jalur CMA maupun jalur CDA.
• Permintaan yang gagal dalam pemeriksaan ditolak dengan HTTP 403. Kode yang dikembalikan tercantum di Error di bawah.

Error

Berikut adalah kode yang muncul saat Anda menangani Space Access Token. Untuk kode yang berlaku umum pada semua sumber daya, lihat Error umum.

API

Base URL untuk semua endpoint di bawah adalah https://cma.weegloo.com/v1, dan diperlukan token Bearer untuk autentikasi CMA pada header Authorization. Pengubahan dan pengubahan sebagian Space Access Token tidak memerlukan header X-Weegloo-Version.

Dokumen terkait

• SpaceRole: mendefinisikan peran (cakupan baca-tulis) yang akan diikat ke token ini.
• Delivery Access Token: token pengiriman hanya-baca yang dibuka kepada pengunjung (untuk klien).
• Personal Access Token: token Weegloo User untuk server dan CI yang terikat pada seluruh akun.
• Paket Harga: batas jumlah penerbitan Space Access Token per paket.