Mengelola Kunci API

Open Cloud mengautentikasi dan mengotorisasi akses API dengan menggunakan kunci API, yang memungkinkan Anda menambahkan izin yang lebih terperinci dan kontrol keamanan untuk mengakses dan memanfaatkan sumber daya tertentu dalam permainan 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.

Buat 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 umumnya dapat mengakses sumber daya apa pun yang memiliki izin, termasuk permainan individu mereka dan permainan yang dimiliki grup di mana mereka memiliki peran yang sesuai. Beberapa cakupan dapat dibatasi untuk permainan 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.

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 permainan 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 permainan yang ingin Anda akses dengan kunci API.

   Anda dapat secara opsional menonaktifkan Batasi berdasarkan Pengalaman. Ketika dinonaktifkan, kunci API Anda memiliki akses ke semua permainan yang dimiliki pengguna Anda dan permainan yang dimiliki grup di mana Anda memiliki izin yang sesuai, termasuk permainan yang Anda buat di masa depan.

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 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 Anda hanya menggunakan kunci API di lingkungan lokal, Anda dapat membiarkan 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 ke lokasi yang aman, bukan repositori publik untuk kode Anda.

11. Verifikasi status kunci API Anda di halaman Ekstensi API dari 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 permainan pribadi di luar grup. Jika Anda menggunakan kunci API akun pribadi Anda untuk otomatisasi grup dan kunci tersebut terkompromi, sumber daya lain yang Anda akses juga berisiko.

Untuk mencegah hal ini, kami sangat merekomendasikan untuk membuat kunci API terpisah di akun alternatif yang didedikasikan dengan akses yang sangat terbatas hanya untuk grup target. Akun baru ini yang didedikasikan untuk tujuan otomatisasi harus hanya 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 di 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 dijaga keamanannya 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 kunci terkompromi.

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

• Gunakan pembatasan alamat IP: Batasi akses kunci API ke alamat IP tertentu atau rentang CIDR 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 terkompromi. Mengatur tanggal kedaluwarsa tidak disarankan untuk kasus penggunaan jangka panjang kecuali Anda memiliki proses rotasi kunci yang diterapkan, 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 dapat terekspos. Gunakan sistem manajemen rahasia untuk menyimpan dan mengontrol akses ke kunci Anda. Di tempat Roblox, gunakan Penyimpanan Rahasia.

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

Format CIDR

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

• Normal: 192.168.0.0
• CIDR: 192.168.0.0/24

Bagian sebelumnya adalah alamat IP dan bagian 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 masa hidupnya. Untuk mengetahui mengapa status kunci API telah berubah dan bagaimana mengembalikan kunci API 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 peminta dan apakah kunci atau pengguna terakhir yang dihasilkan sedang dimoderasi.

Permintaan

(application/json)

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 pencipta. 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 pada semua sumber daya dari jenis tersebut.

{
  "name": "kunci uji",
  "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"
}