Autentikasi dan Kunci API

API Discuse mengautentikasi setiap permintaan dengan kunci API. Kirimkan kunci tersebut di header permintaan X-API-Key (atau sebagai field api_key di body JSON). Kunci diawali dengan prefiks disc_, terikat ke satu proyek, dan hanya ditampilkan secara lengkap satu kali saat dibuat. Panduan ini membahas cara mendapatkan, menggunakan, mengamankan, dan merotasinya.

Bagaimana cara kerja autentikasi Discuse?

Setiap panggilan API harus menyertakan kunci API yang valid. Discuse menggunakannya untuk:

Melacak penggunaan terhadap kuota proyek Anda
Menerapkan pembatasan laju per kunci untuk mencegah penyalahgunaan
Mengaitkan permintaan dengan proyek yang tepat beserta pengaturannya
Mengontrol akses ke sumber daya akun Anda

Mendapatkan Kunci API Anda

Langkah 1: Buat Akun

Jika belum, daftar akun Discuse di discuse.com. Anda bisa memulai dengan paket Basic gratis, yang mencakup jatah bulanan permintaan API serta akses ke pemeriksaan teks, spam, bahasa, dan gambar. Lihat halaman harga untuk mengetahui batas terbaru per paket.

Langkah 2: Akses Dashboard

Setelah masuk, buka dashboard Anda. Cari bagian "API Keys" atau "Developer" di menu navigasi.

Langkah 3: Buat Kunci Baru

Klik "Create New API Key" dan, jika perlu, berikan nama atau deskripsi untuk kunci tersebut. Ini membantu Anda mengenali tujuan setiap kunci jika Anda membuat lebih dari satu.

Kunci API baru Anda hanya akan ditampilkan satu kali. Segera salin dan simpan dengan aman - Anda tidak akan bisa melihat kunci lengkapnya lagi.

Menggunakan Kunci API Anda

Sertakan kunci API Anda di header X-API-Key pada setiap permintaan:

curl -X POST https://api.discuse.com/api/v2/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: disc_aB3dEf6GhIjKlMnOpQrStUvWxYz012345" \
  -d '{
    "content": {
      "text": "Content to analyze"
    }
  }'

Sebagai alternatif, Anda dapat mengirimkan kunci sebagai field api_key di dalam body JSON alih-alih header — header lebih disarankan agar kunci tidak pernah masuk ke log body permintaan.

Contoh JavaScript

const response = await fetch('https://api.discuse.com/api/v2/check', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.DISCUSE_API_KEY
  },
  body: JSON.stringify({
    content: { text: 'Content to analyze' }
  })
});

Contoh Python

import requests
import os

response = requests.post(
    'https://api.discuse.com/api/v2/check',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': os.environ['DISCUSE_API_KEY']
    },
    json={
        'content': {'text': 'Content to analyze'}
    }
)

Praktik Terbaik Keamanan Kunci API

Jangan Pernah Mengekspos Kunci di Kode Sisi Klien

Kunci API tidak boleh pernah disertakan dalam JavaScript yang berjalan di browser. Kode sisi klien dapat dilihat oleh siapa pun yang membuka sumber halaman Anda.

// WRONG - Don't do this!
const API_KEY = 'disc_aB3dEf6...'; // Exposed in browser

// CORRECT - Use a backend proxy
const response = await fetch('/api/moderate', {
  method: 'POST',
  body: JSON.stringify({ text: userInput })
});

Gunakan Variabel Lingkungan

Simpan kunci API di variabel lingkungan, bukan di basis kode Anda:

# .env file (add to .gitignore!)
DISCUSE_API_KEY=disc_aB3dEf6GhIjKlMnOpQrStUvWxYz012345

// Access in Node.js
const apiKey = process.env.DISCUSE_API_KEY;

Rotasi Kunci Secara Berkala

Rotasikan kunci API Anda secara berkala, terutama jika Anda mencurigai kunci tersebut mungkin telah bocor:

Buat kunci API baru
Perbarui aplikasi Anda agar menggunakan kunci baru
Pastikan semuanya berfungsi dengan benar
Cabut kunci lama

Catatan: kunci yang sudah dicabut masih dapat digunakan hingga sekitar 5 menit karena kunci yang telah divalidasi disimpan di cache. Rencanakan rotasi dengan mempertimbangkan jeda singkat tersebut, bukan mengharapkan perpindahan instan.

Gunakan Kunci Terpisah untuk Lingkungan yang Berbeda

Buat kunci API berbeda untuk development, staging, dan production:

Lingkungan	Tujuan Kunci
Development	Pengujian dan pengembangan lokal
Staging	Pengujian pra-produksi
Production	Trafik aplikasi live

Dengan begitu, Anda dapat mencabut kunci yang bocor tanpa memengaruhi lingkungan lain.

Bagaimana cara kerja pembatasan laju?

Pembatasan laju berlaku per kunci API, bukan per paket. Setiap kunci memiliki batas requests-per-minute (RPM) yang ditetapkan saat kunci dibuat; jika Anda tidak menentukannya, nilai default-nya adalah 60 permintaan per menit. Kunci yang berbeda pada akun yang sama dapat memiliki batas berbeda, sehingga Anda bisa memberikan RPM yang lebih tinggi untuk layanan dengan throughput tinggi dibandingkan integrasi sekali pakai.

Ketika sebuah kunci melampaui batas RPM-nya, permintaan akan gagal dengan status HTTP 429 Too Many Requests yang message-nya menyatakan bahwa batas laju telah terlampaui. Penghitung pembatasan laju direset dalam jendela bergulir satu menit.

Menangani batas laju

Lakukan backoff dan coba lagi pada 429 (dan pada 5xx sementara). Karena jendelanya satu menit, exponential backoff yang dimulai sekitar satu detik lalu meningkat biasanya bekerja dengan baik:

async function checkWithRetry(content, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch('https://api.discuse.com/api/v2/check', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': process.env.DISCUSE_API_KEY
      },
      body: JSON.stringify({ content })
    });

    if (response.status === 429 || response.status >= 500) {
      const delay = 1000 * Math.pow(2, attempt); // 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }

    return response.json();
  }
  throw new Error('Max retries exceeded');
}

Respons error apa saja yang bisa saya terima?

Situasi	Status HTTP
Permintaan tidak valid (konten kosong, teks lebih dari 10.000 karakter, terlalu banyak URL)	`400` validasi permintaan
Kunci API tidak ada atau tidak valid	`401`
Batas laju terlampaui untuk kunci tersebut	`429`
Kuota periode penagihan habis	`200` dengan `message` dan `usage` (bukan status error)

Kuota yang habis memang sengaja tidak dianggap sebagai error HTTP: respons /api/v2/check tetap mengembalikan 200 dengan has_violations: false, sebuah message yang menjelaskan bahwa kuota telah habis, dan objek usage yang menampilkan api_requests_remaining: 0. Periksa field-field tersebut alih-alih mengandalkan kode status. Kegagalan autentikasi mengembalikan 401, pembatasan laju 429, dan kegagalan validasi permintaan 400. Lihat referensi Kode Error dan Respons untuk daftar lengkapnya.

Mengelola Beberapa Kunci

Untuk tim yang lebih besar atau aplikasi yang kompleks, Anda mungkin memerlukan beberapa kunci API:

Kasus Penggunaan untuk Beberapa Kunci

Kunci per lingkungan: Kunci terpisah untuk dev, staging, dan production
Kunci per layanan: Kunci berbeda untuk microservice yang berbeda
Kunci per tim: Pisahkan penggunaan berdasarkan tim untuk penagihan internal
Kunci sementara: Kunci berumur pendek untuk kontraktor atau integrasi

Praktik Terbaik Pengelolaan Kunci

Beri nama kunci secara deskriptif: "Production - User Service", "Staging - Backend"
Dokumentasikan penggunaan kunci: Simpan catatan tentang kunci mana yang digunakan di mana
Siapkan peringatan: Pantau pola penggunaan yang tidak biasa
Audit rutin: Tinjau dan bersihkan kunci yang tidak digunakan setiap kuartal

Langkah Berikutnya

Panduan Mulai Cepat - Lakukan panggilan API pertama Anda
Analisis Teks - Pelajari deteksi sentimen
Menskalakan Moderasi Konten - Pola implementasi untuk volume tinggi