Delivery Access Token

DeliveryAccessToken adalah token baca yang digunakan untuk membaca konten yang telah dipublikasikan dari CDA (pengiriman publik). Saat browser sebuah situs web atau aplikasi mengambil konten yang dipublikasikan, ia memanggil CDA dengan token ini. Saat diterbitkan, token diikat ke satu SpaceRole, dan peran itulah yang menentukan cakupan baca token (yaitu Content Type mana saja yang boleh dibaca).

Di CMA, DeliveryAccessToken merupakan sumber daya turunan dari Space, dan path-nya mengacu pada /spaces/{spaceId}/delivery-access-tokens. Karena token ini bekerja dalam keadaan terekspos ke browser (klien), peran yang diikat harus ditetapkan dengan hak paling minimal (least-privilege) yang hanya membaca Content Type yang benar-benar diperlukan (lihat Keamanan: pengikatan hak minimal di bawah). Selain itu, jika Anda memuat origin yang diizinkan memanggil token ini ke dalam allowedReferrers, token ini tidak dapat dipakai di luar situs yang Anda tetapkan (lihat Aturan penulisan origin dan Pemeriksaan Referer).

Struktur sumber daya

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

{
  "sys": {
    "id": "3trmXRM3RqbgSnifyg7PUFQuOAqWOc",
    "type": "DeliveryAccessToken",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "user": { "sys": { "id": "3trmXRLdJIqc9GPBbyFYQQw6hf9kGj", "type": "Refer", "targetType": "User" } },
    "createdBy": { "sys": { "id": "3trmXRM3RqbgSnifyg7PUFQsSPi0nt", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-06-18T09:24:23.156Z",
    "updatedBy": { "sys": { "id": "3trmXRM3RqbgSnifyg7PUFQsSPi0nt", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-06-18T09:24:23.156Z",
    "accessToken": "DVRATbQ8mX2vK9pLs7Rf1Zt0Nc4Wd6Hg5Ua2Ee9Ck3PoYx8Bj6Hg5Ua2Ee9Ck3Po…",
    "scopes": ["DELIVERY_ACCESS_TOKEN"]
  },
  "allowedReferrers": ["https://shop.example.com"],
  "description": "Token pengiriman hanya-baca untuk situs publik toko pakaian",
  "name": "Pengiriman situs web publik"
}

Kunci utama:

• sys.id: pengenal unik DeliveryAccessToken. Nilai ini masuk ke {deliveryAccessTokenId} pada path baca, ubah, dan hapus tunggal.
• sys.accessToken: nilai token rahasia yang digunakan untuk memanggil CDA. Nilai yang sama tetap muncul apa adanya pada pembacaan setelah penerbitan, jadi berhati-hatilah agar tidak terekspos (lihat bagian keamanan di bawah).
• sys.scopes: cakupan hak token. Saat diterbitkan, DeliveryAccessToken selalu bernilai ["DELIVERY_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: Pengiriman situs web publik).
• description: deskripsi token (opsional).
• allowedReferrers: daftar yang membatasi dari origin mana token ini boleh dipanggil. Jika daftar ini kosong, panggilan tidak dibatasi. Token pada contoh di atas hanya lolos ketika dipanggil dari situs publik toko pakaian, yaitu https://shop.example.com. Untuk aturan penulisan dan cara pemeriksaan, lihat Aturan penulisan origin dan Pemeriksaan Referer.

accessToken pada contoh di atas adalah nilai rahasia, sehingga diganti dengan string contoh. Nilai sebenarnya berupa string panjang dan tidak transparan, dan akan tetap sama ketika dibaca kembali setelah diterbitkan.

Properti sistem (sys)

Setiap DeliveryAccessToken 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:

Keamanan: pengikatan hak minimal

DeliveryAccessToken adalah token yang memanggil CDA dalam keadaan terekspos ke browser dan pengunjung. Karena itu, SpaceRole mana yang diikat menjadi batas keamanan token ini.

• Pada role di permintaan pembuatan, masukkan sys.id dari SpaceRole berhak minimal yang hanya membaca Content Type yang diperlukan. Untuk pengiriman publik, disarankan peran baca-saja.
• Jangan pernah mengikat peran Administrator. Karena token ini terekspos ke klien, mengikat peran yang membawa hak administrasi berarti hak itu bocor langsung ke luar. Selain itu, jangan asal memakai item pertama dari daftar SpaceRole; tentukan secara eksplisit sys.id dari peran berhak minimal yang Anda maksud.
• Dengan allowedReferrers, batasi juga tempat token ini boleh dipakai. Peran yang diikat menentukan apa yang dapat dibaca dengan token ini, sedangkan daftar tersebut menentukan dari mana token ini dapat dipanggil. Nilai token yang bekerja di browser tidak dapat disembunyikan, jadi jika Anda memuat origin situs publik ke dalam daftar itu, panggilan CDA dari luar situs tersebut tidak akan lolos meskipun nilai token bocor ke luar (lihat Pemeriksaan Referer).
• accessToken adalah nilai rahasia yang dibaca dengan nilai yang sama bahkan setelah diterbitkan. Suntikkan secara aman ke build klien, tetapi jangan ekspos apa adanya ke luar.

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 di Space itu, 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.
• DeliveryAccessToken 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_DELIVERY_ACCESS_TOKEN pada settings dari peran pemanggil. Aksi ini terpisah dari SETTING_SPACE_ACCESS_TOKEN, yang menerbitkan Space Access Token berkemampuan tulis, sehingga Anda dapat memberikan izin penerbitan token pengiriman saja sambil tetap melarang penerbitan token tulis (lihat SpaceRole).
• API ini hanya dapat dipanggil dengan sesi login konsol dan Personal Access Token. DeliveryAccessToken yang sudah diterbitkan tidak dapat membuat DeliveryAccessToken lain.

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 CDA 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. Browser mengirim header ini dengan sendirinya, tetapi untuk token yang akan dipakai di tempat yang tidak mengirim Referer, misalnya skrip build yang berjalan di server atau perenderan di sisi server, 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, apa pun jalur CDA yang Anda panggil.
• 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 DeliveryAccessToken. 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 DeliveryAccessToken tidak memerlukan header X-Weegloo-Version.

Dokumen terkait

• SpaceRole: mendefinisikan peran (cakupan baca) yang akan diikat ke token ini.
• Ringkasan CDA: API pengiriman yang membaca konten yang dipublikasikan dengan token ini.
• Space Access Token: token yang juga dapat menulis di dalam satu Space dan memiliki pembatasan origin yang sama.
• Personal Access Token: token Weegloo User untuk server dan CI.