Kelola kunci API

Open Cloud mengautentikasi dan mengotorisasi akses API dengan penggunaan kunci API, yang memungkinkan Anda menambahkan izin granular dan kontrol keamanan untuk mengakses dan memanfaatkan sumber daya tertentu dalam game Anda, seperti penyimpanan data dan tempat.

Semua API Open Cloud mengharuskan Anda untuk membuat kunci API dengan izin yang valid dan menyertakan header x-api-key dalam permintaan Anda, yang memungkinkan aplikasi untuk mengautentikasi ke Open Cloud atas nama Anda.

Membuat kunci API

Anda dapat membuat dan mengonfigurasi kunci API untuk mengakses sumber daya Anda. Akses kunci API ditentukan oleh izin pengguna yang memilikinya. Ini berarti kunci tersebut secara umum dapat mengakses sumber daya apa pun yang memiliki izin oleh pengguna, termasuk game individu mereka dan game yang dimiliki grup di mana mereka memiliki peran yang sesuai. Beberapa cakupan dapat dibatasi pada game tertentu, tetapi tidak semuanya.

Untuk detail tentang cara membuat kunci API untuk mengelola sumber daya grup, lihat bagian Buat kunci API untuk mengelola sumber daya yang dimiliki grup di bawah ini.

Untuk membuat kunci API:

1. Di Dasbor Pembuat, pergi ke halaman Kunci API.

2. Klik tombol Buat Kunci API.

3. Masukkan nama unik untuk kunci API Anda. Gunakan nama yang dapat membantu Anda mengingat tujuan nanti, seperti PLACE_PUBLISHING_KEY untuk menerbitkan tempat ke game Anda.

4. Di bagian Izin Akses, pilih API dari menu Pilih Sistem API. Ulangi langkah ini jika Anda perlu menambahkan beberapa API ke kunci.

5. Jika berlaku, pilih game yang ingin Anda akses dengan kunci API tersebut.

   Anda dapat memilih untuk menonaktifkan Batasi berdasarkan Pengalaman. Saat dinonaktifkan, kunci API Anda memiliki akses ke semua game yang dimiliki pengguna dan game yang dimiliki grup di mana Anda memiliki izin yang sesuai, termasuk game apa pun yang Anda buat di masa mendatang.

6. Dari dropdown Pilih Operasi, pilih operasi yang ingin Anda aktifkan untuk kunci API.

   Sebagian besar operasi dalam referensi API mencakup cakupan izin yang diperlukan. Misalnya, operasi flush memory store memerlukan izin universe.memory-store:flush.

   Untuk daftar semua cakupan dan API yang mereka dukung, lihat Cakupan.

7. (Opsional) Di bagian Keamanan, batasi akses IP ke kunci tersebut secara eksplisit menggunakan notasi CIDR. Anda dapat menemukan alamat IP mesin lokal Anda dan menambahkannya ke bagian Alamat IP yang Diterima bersama dengan alamat IP tambahan untuk mereka yang memerlukan akses. Jika Anda tidak memiliki IP tetap, atau jika Anda menggunakan kunci API hanya di lingkungan lokal, Anda dapat meninggalkan toggle Batasi alamat IP tidak dicentang untuk memungkinkan IP mana pun menggunakan kunci API Anda.

8. (Opsional): Untuk menambahkan perlindungan tambahan untuk sumber daya Anda, atur tanggal kedaluwarsa untuk kunci Anda.

9. Klik tombol Simpan & Hasilkan kunci.

10. Salin dan simpan string kunci API di lokasi yang aman, tidak di repositori publik untuk kode Anda.

11. Verifikasi status kunci API Anda di halaman Ekstensi API di Dasbor Pembuat.

Buat kunci API untuk mengelola sumber daya yang dimiliki grup

Kunci API memberikan akses ke semua sumber daya yang memiliki izin untuk akun pengguna, termasuk game pribadi di luar grup. Jika Anda menggunakan kunci API akun pribadi untuk otomatisasi grup dan kunci itu dikompromikan, sumber daya lain yang Anda miliki juga berisiko.

Untuk mencegah hal ini, kami sangat merekomendasikan untuk membuat kunci API terpisah di akun alternatif yang didedikasikan dengan akses yang dibatasi ketat untuk grup target. Akun baru ini yang didedikasikan untuk tujuan otomatisasi hanya boleh diberikan akses ke grup target dan diberikan izin minimal yang diperlukan untuk tugasnya.

1. Buat akun Roblox baru yang didedikasikan untuk otomatisasi Anda.
2. Undang akun baru ke grup Anda.
3. Berikan peran grup dengan izin minimum yang diperlukan untuk tugasnya (misalnya, hanya "Buat dan edit pengalaman grup").
4. Masuk ke akun baru dan ikuti langkah-langkah di bagian atas untuk membuat kunci API.
5. Gunakan kunci API yang dihasilkan untuk otomatisasi sumber daya grup.

Praktik Terbaik Untuk Mengelola Kunci API

Kunci API adalah kredensial sensitif yang harus tetap aman untuk mencegah akses tidak sah ke data Anda. Berikut adalah beberapa praktik terbaik untuk mengelola kunci API.

• Buat kunci terpisah untuk setiap aplikasi: Buat kunci API terpisah untuk setiap aplikasi atau kasus penggunaan untuk mengisolasi akses dan mengurangi dampak jika sebuah kunci dikompromikan.

• Pilih izin minimum yang dibutuhkan: Saat mengonfigurasi cakupan, pilih izin minimum yang diperlukan untuk penggunaan yang dimaksudkan dari kunci tersebut. Untuk cakupan yang memungkinkan Anda membatasi akses cakupan berdasarkan game, batasi akses hanya pada game tertentu yang diperlukan.

• Gunakan pembatasan alamat IP: Batasi akses kunci API ke alamat IP atau rentang CIDR tertentu untuk mencegah penggunaan tidak sah dari lokasi yang tidak dikenal. Jangan gunakan pembatasan alamat IP saat menggunakan kunci API Anda di tempat Roblox untuk memastikan kunci Anda dapat digunakan dengan server Roblox.

• Atur tanggal kedaluwarsa: Untuk kasus penggunaan jangka pendek, konfigurasikan tanggal kedaluwarsa untuk secara otomatis menonaktifkan kunci setelah periode tertentu, mengurangi risiko jika kunci dikompromikan. Menetapkan tanggal kedaluwarsa tidak disarankan untuk kasus penggunaan jangka panjang kecuali Anda memiliki proses rotasi kunci yang siap, karena otomatisasi Anda dapat gagal secara tidak terduga ketika kunci kedaluwarsa.

• Gunakan akun alternatif yang didedikasikan untuk manajemen sumber daya grup: Gunakan akun yang didedikasikan dengan izin minimal untuk manajemen sumber daya grup, seperti yang dijelaskan dalam bagian Buat kunci API untuk mengelola sumber daya yang dimiliki grup.

• Simpan kunci API dengan aman: Jangan pernah menyimpan kunci API langsung di kode sumber Anda, sistem kontrol versi, atau skrip di mana mereka bisa terpapar. Gunakan sistem manajemen rahasia untuk menyimpan dan mengontrol akses ke kunci Anda. Di tempat Roblox, gunakan Secrets Store.

• Jangan bagi kunci API melalui saluran publik: Jangan pernah membagikan kunci API melalui saluran komunikasi publik, forum, atau media sosial. Hanya bagikan kunci melalui saluran privat yang aman dengan anggota tim tepercaya. Batasi akses kepada siapa Anda membagikan kunci Anda untuk meminimalkan radius ledakan jika kunci dikompromikan.

Format CIDR

Untuk melindungi sumber daya Anda lebih lanjut, saat membuat kunci API, tentukan alamat IP yang dapat mengakses kunci API dengan alamat IP normal atau menggunakan notasi CIDR. Alamat IP CIDR terlihat seperti alamat IP normal kecuali diakhiri dengan garis miring dan desimal yang menggambarkan seberapa banyak bit dari alamat IP yang penting untuk pengalihan jaringan:

• Normal: 192.168.0.0
• CIDR: 192.168.0.0/24

Bagian sebelumnya adalah alamat IP dan bagian yang terakhir adalah netmask, menghitung bit 1 dalam format biner. Dalam contoh sebelumnya, 24 berarti 255.255.255.0 (24 1s) yang memungkinkan semua IP antara 192.168.0.0 dan 192.168.0.255. Memahami format CIDR sangat berguna jika Anda berencana menjalankan aplikasi Anda di server.

Status kunci API

Kunci API pada awalnya memiliki status aktif, tetapi dapat menjadi tidak aktif selama umur mereka. Untuk mempelajari mengapa sebuah kunci API telah berubah status dan bagaimana mengembalikan kunci API kembali ke status aktif, lihat tabel berikut.

Introspeksi kunci API

POST api-keys/v1/introspect

Ambil informasi tentang kunci API. Memverifikasi apakah kunci dapat digunakan dari alamat IP pemohon dan apakah kunci atau pengguna terakhir yang dihasilkan sedang dimoderasi.

Permintaan

(application/json)

Contoh Permintaan Kunci API Introspeksi
curl --location --request POST 'https://apis.roblox.com/api-keys/v1/introspect' \
--header 'Content-Type: application/json' \
--data '{
    "apiKey": "your-api-key"
}'

Respons

Ada empat pengidentifikasi sumber daya yang mungkin ada di setiap objek cakupan:

• userId
• groupId
• universeId
• universeDatastore

Pengidentifikasi userId dan groupId hanya relevan untuk cakupan dengan target pembuat. Pengidentifikasi universeDatastore hanya relevan untuk cakupan dengan target universe-datastore. Pengidentifikasi sumber daya akan dihilangkan untuk cakupan yang tidak mendukung pemilihan sumber daya.

Sebuah asterisk (*) dalam daftar pengidentifikasi sumber daya menunjukkan bahwa cakupan memiliki izin untuk semua sumber daya dari jenis itu.

Contoh Respons Kunci API Introspeksi
{
  "name": "test key",
  "authorizedUserId": 234,
  "scopes": [
    {
      "name": "universe-datastores.objects",
      "operations": [
        "create"
      ],
      "universeDatastores": [
        {
          "universeId": "123",
          "datastoreName": "playerData"
        }
      ]
    },
    {
      "name": "asset",
      "operations": [
        "write"
      ],
      "groupIds": [
        "*"
      ],
      "userIds": [
        "*"
      ]
    }
  ],
  "enabled": true,
  "expired": false,
  "expirationTimeUtc": "2026-01-01T12:00:00.000Z"
}