Kunci API vs JWT vs OAuth2: pilih autentikasi yang tepat untuk API Anda

Anda sedang membangun API. Titik akhir berfungsi. Data mengalir. Sekarang Anda perlu menjawab satu pertanyaan sebelum pengiriman: bagaimana penelepon membuktikan siapa mereka?

Tiga pendekatan mendominasi autentikasi API: kunci API, JWT, dan OAuth2. Masing-masing memecahkan a masalah yang berbeda. Pilih yang salah dan Anda akan merekayasa integrasi sederhana secara berlebihan atau meninggalkan celah keamanan dalam hal yang kompleks.

Panduan ini membandingkan ketiganya dalam tujuh kriteria, dengan contoh kode kerja, dan keputusan tabel, dan rekomendasi yang jelas berdasarkan kasus penggunaan API Anda.

Otentikasi kunci API: pendekatan langsung

Kunci API adalah string acak panjang yang mengidentifikasi dan memberi otorisasi pada pemanggil. Klien mengirim itu dengan setiap permintaan, server mencarinya, dan jika cocok dengan kunci yang valid, permintaan tersebut melewati.

Berikut tampilan panggilan kunci API dengan botoi API:

# API key in a custom header
curl -s -X POST https://api.botoi.com/v1/dns/lookup \\
  -H "Content-Type: application/json" \\
  -H "x-api-key: your_api_key_here" \\
  -d '{"domain": "example.com", "type": "A"}'

Tanggapan:

{
  "success": true,
  "data": {
    "domain": "example.com",
    "type": "A",
    "records": [
      { "type": "A", "value": "93.184.216.34", "ttl": 86400 }
    ]
  }
}

Itu x-api-key header membawa kredensial. Tidak ada token untuk dinegosiasikan, tidak ada pengalihan, tidak ada server otorisasi. Satu header, satu pencarian, satu respons.

Saat kunci API menang

• Panggilan server-ke-server. Backend Anda memanggil backend lain. Tidak ada pengguna terlibat. Tugas cron menanyakan API geolokasi IP. Alur CI menjalankan pemeriksaan DNS. Penelepon selalu merupakan server tepercaya.
• API Utilitas. API yang melakukan operasi tanpa kewarganegaraan (hashing, pengkodean, validasi, pencarian) di mana setiap permintaan bersifat independen. botoi menggunakan kunci API karena alasan ini: 150+ titik akhir, semuanya tanpa kewarganegaraan, semua server-ke-server.
• Integrasi cepat. Pengembang menyalin kunci, menambahkan satu header, dan memulai menelepon. Tidak ada tarian OAuth, tidak ada logika penyegaran token, tidak ada titik akhir JWKS yang perlu dikonfigurasi.

Inilah panggilan yang sama di Node.js:

const response = await fetch("https://api.botoi.com/v1/hash", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.BOTOI_API_KEY,
  },
  body: JSON.stringify({ text: "hello world", algorithm: "sha256" }),
});

const result = await response.json();
// result.data.hash = "b94d27b9934d3e08..."

Dimana kunci API gagal

• Tidak ada identitas pengguna. Kunci API mengidentifikasi akun, bukan pengguna. Jika tiga pengembang berbagi satu kunci, Anda tidak dapat mengetahui siapa yang membuat permintaan mana.
• Pencabutan memerlukan perjalanan bolak-balik. Mencabut kunci berarti memperbarui server toko kunci. Hingga cache disegarkan, kunci lama masih berfungsi.
• Tidak ada akses yang didelegasikan. Anda tidak dapat memberikan aplikasi pihak ketiga secara terbatas, bersifat sementara akses ke sumber daya pengguna hanya dengan kunci API.

Otentikasi JWT: sesi pengguna tanpa kewarganegaraan

JSON Web Token (JWT) adalah objek JSON bertanda tangan yang membawa klaim tentang pemanggil. Penulis server membuatnya saat login; klien mengirimkannya dengan setiap permintaan; server sumber daya memverifikasi tanda tangan tanpa memanggil server autentikasi lagi.

// Header
{
  "alg": "RS256",
  "typ": "JWT"
}

// Payload
{
  "sub": "user_12345",
  "email": "dev@example.com",
  "role": "admin",
  "iat": 1775000000,
  "exp": 1775000900   // 15 minutes
}

// Signature
RSASHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  privateKey
)

Server memverifikasi tanda tangan dengan kunci publik. Jika tanda tangan dicentang dan exp belum lulus, permintaan diotorisasi. Tidak diperlukan pencarian basis data.

Saat JWT menang

• API yang dapat dilihat pengguna dengan lalu lintas tinggi. Aplikasi seluler mengirimkan JWT ke setiap permintaan. Gateway API memverifikasi tanda tangan secara lokal alih-alih menanyakan penyimpanan sesi di setiap panggilan. Dengan 10.000 permintaan per detik, panggilan database yang Anda lewati itu penting.
• Arsitektur layanan mikro. Layanan A memanggil Layanan B dengan JWT. Layanan B memvalidasinya secara lokal dan mengekstrak ID pengguna dan peran dari klaim. Tidak ada sesi bersama database antar layanan.
• Otorisasi berumur pendek. Token 15 menit untuk mengunggah file. 5 menit token untuk konfirmasi pembayaran. Kedaluwarsanya dimasukkan ke dalam token itu sendiri.

Inilah middleware Express yang memverifikasi JWT:

import jwt from "jsonwebtoken";

function authMiddleware(req, res, next) {
  const token = req.headers.authorization?.replace("Bearer ", "");
  if (!token) return res.status(401).json({ error: "Missing token" });

  try {
    const decoded = jwt.verify(token, process.env.JWT_PUBLIC_KEY, {
      algorithms: ["RS256"],
    });
    req.user = decoded;
    next();
  } catch (err) {
    return res.status(401).json({ error: "Invalid or expired token" });
  }
}

Dimana JWT gagal

• Pencabutan token itu sulit. JWT berlaku sampai habis masa berlakunya. Jika pengguna login keluar atau Anda perlu mencabut akses, Anda memerlukan daftar blokir sisi server, yang mengembalikannya panggilan basis data yang ingin Anda hindari.
• Ukuran muatan. Setiap klaim menambahkan byte. JWT dengan peran pengguna, izin, dan metadatanya bisa mencapai 1-2 KB. Itu berarti 1-2 KB pada setiap permintaan, di setiap header.
• Kompleksitas rotasi kunci. Saat Anda memutar kunci penandatanganan, token lama ditandatangani dengan kunci sebelumnya harus tetap valid hingga habis masa berlakunya. Ini berarti melayani banyak orang kunci publik melalui titik akhir JWKS dan menanganinya kid klaim tajuk.

OAuth2: akses yang didelegasikan untuk pihak ketiga

OAuth2 adalah kerangka otorisasi, bukan protokol otentikasi. Ini memungkinkan pengguna memberikan a aplikasi pihak ketiga membatasi akses ke sumber daya mereka di layanan lain, tanpa berbagi kata sandi mereka.

Contoh klasik: pengguna memberi otorisasi pada alat manajemen proyek untuk membaca GitHub mereka repositori. Pengguna masuk ke GitHub, menyetujui cakupan tertentu, dan alat tersebut menerima token akses yang dicakup dalam izin tersebut.

# Step 1: Redirect user to authorization server
GET https://auth.example.com/authorize?
  response_type=code&
  client_id=your_app_id&
  redirect_uri=https://yourapp.com/callback&
  scope=read:repos+write:issues&
  state=random_csrf_token

# Step 2: Exchange authorization code for tokens
POST https://auth.example.com/token
  grant_type=authorization_code&
  code=AUTH_CODE_FROM_CALLBACK&
  client_id=your_app_id&
  client_secret=your_app_secret&
  redirect_uri=https://yourapp.com/callback

# Step 3: Call the API with the access token
curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..." \\
  https://api.example.com/v1/repos

Saat OAuth2 menang

• Integrasi pihak ketiga. Anda menjalankan platform dan menginginkan pengembang eksternal untuk membangun aplikasi yang mengakses data pengguna Anda. OAuth2 memberi pengguna kendali atas masing-masing aplikasi dapat mengakses.
• Cakupan berbutir halus. read:repos tapi tidak delete:repos. write:issues tapi tidak admin:org. OAuth2 cakupan memungkinkan pengguna menyetujui izin tertentu.
• Arus "Masuk dengan X". Saat aplikasi Anda menggunakan Google, GitHub, atau Microsoft untuk login, Anda menggunakan OAuth2 (seringkali dengan OpenID Connect di atas) untuk mendapatkan token identitas.

Dimana OAuth2 gagal

• Kompleksitas. OAuth2 memiliki empat jenis hibah, token penyegaran, otorisasi server, URI pengalihan, PKCE, dan titik akhir introspeksi token. Untuk API utilitas dengan tidak ada konteks pengguna, ini adalah overhead tanpa manfaat.
• Gesekan integrasi. Pengembang yang ingin menghubungi titik akhir hash Anda tidak ingin mendaftarkan aplikasi OAuth, menyiapkan URI pengalihan, dan otorisasi pertukaran kode. Mereka menginginkan kunci dan perintah curl.
• Beban manajemen token. Token akses kedaluwarsa. Segarkan token berputar. Klien memerlukan logika percobaan ulang untuk respons 401. Untuk panggilan server-ke-server sederhana, ini adalah mesin yang tidak perlu.

Tabel perbandingan

Kriteria	Kunci API	JWT	OAuth2
Waktu integrasi	Menit	Jam	hari
Identitas pengguna	Tingkat akun	Tingkat pengguna (klaim)	Tingkat pengguna (cakupan)
Verifikasi tanpa kewarganegaraan	Tidak (pencarian server)	Ya (cek tanda tangan)	Tergantung pada format token
Kecepatan pencabutan	Segera (hapus kunci)	Tertunda (sampai habis masa berlakunya)	Segera (cabut token)
Akses yang didelegasikan	TIDAK	TIDAK	Ya
Dukungan pihak ketiga	Miskin	Bagus	Bagus sekali
Cocok untuk browser	Tidak (eksposur kunci)	Ya (berumur pendek)	Ya (kode otorisasi + PKCE)

Kerangka keputusan: pilih berdasarkan kasus penggunaan Anda

Berhentilah bertanya "mana yang paling aman?" Ketiganya aman bila digunakan dengan benar. Benar pertanyaan: "siapa yang memanggil API saya dan mengapa?"

• Server memanggil server, tidak ada pengguna yang terlibat: Kunci API. Panggilan backend Anda a API utilitas untuk pencarian DNS, hashing, atau validasi data. Satu kunci, satu header, selesai.
• Aplikasi Anda sendiri mengautentikasi pengguna Anda sendiri: JWT. Aplikasi seluler atau SPA Anda mengirimkan permintaan atas nama pengguna yang masuk. Tanda tangani JWT berumur pendek saat login, verifikasi pada setiap permintaan tanpa penyimpanan sesi.
• Aplikasi pihak ketiga mengakses data pengguna: OAuth2. Pengembang eksternal membangun integrasi dengan platform Anda. Pengguna mengontrol apa yang dapat diakses setiap aplikasi melalui cakupan layar persetujuan.

Mengelola kunci API dalam skala besar dengan Unkey

Kunci API terdengar sederhana hingga Anda perlu melakukan hashing, menerapkan batas kapasitas, dan menetapkan masa berlaku tanggal, lacak penggunaan per kunci, dan putar tanpa waktu henti. Membangun semua ini dari awal membutuhkan waktu berminggu-minggu.

Buka kuncinya adalah terbuka layanan manajemen kunci API sumber yang menangani pembuatan, verifikasi, pembatasan kecepatan, dan analitik. botoi menggunakan Unkey untuk mengelola semua kunci API di 150+ titik akhirnya.

Buat kunci cakupan dengan pembatasan laju bawaan:

import { Unkey } from "@unkey/api";

const unkey = new Unkey({ rootKey: process.env.UNKEY_ROOT_KEY });

// Create a scoped API key with built-in rate limiting
const key = await unkey.keys.create({
  apiId: "api_your_api_id",
  prefix: "botoi",
  meta: { userId: "user_12345", plan: "pro" },
  expires: Date.now() + 90 * 24 * 60 * 60 * 1000, // 90 days
  ratelimit: {
    type: "fast",
    limit: 100,
    refillRate: 10,
    refillInterval: 1000,
  },
});

// key.result.key = "botoi_3xK9m2..."

Verifikasi di middleware Anda:

import { verifyKey } from "@unkey/api";

async function authMiddleware(req, res, next) {
  const apiKey = req.headers["x-api-key"];
  if (!apiKey) return res.status(401).json({ error: "Missing API key" });

  const result = await verifyKey(apiKey);

  if (!result.result.valid) {
    return res.status(result.result.code === "RATE_LIMITED" ? 429 : 403)
      .json({ error: result.result.code });
  }

  req.keyMeta = result.result.meta; // { userId, plan }
  next();
}

Unkey menyimpan kunci yang di-hash (tidak pernah dalam teks biasa), menerapkan batas kecepatan di edge, dan memberikan Anda memiliki dasbor analitik yang menunjukkan penggunaan per kunci. Saat kunci memerlukan rotasi, buat yang baru dan menetapkan masa berlaku pada yang lama. Tidak ada waktu henti, tidak ada perubahan kode.

Daftar periksa keamanan untuk setiap pendekatan

Kunci API

• Kirim melalui HTTPS saja. Jangan pernah menyematkan kunci di URL atau string kueri.
• Simpan hash di server. Jangan pernah mencatat kunci mentah.
• Kunci cakupan untuk izin tertentu (hanya baca, tulis, admin).
• Tetapkan tanggal kedaluwarsa. Rotasi paksa setiap 90 hari.
• Gunakan tajuk khusus (x-api-key) alih-alih Authorization untuk hindari cache kredensial browser.

JWT

• Gunakan penandatanganan asimetris (RS256 atau ES256). Jangan pernah menggunakan HS256 dengan rahasia bersama sistem terdistribusi.
• Jaga agar masa pakai token tetap singkat: 5-15 menit untuk token akses.
• Mengesahkan iss, aud, Dan exp klaim pada setiap permintaan.
• Publikasikan kunci publik melalui titik akhir JWKS. Putar kunci penandatanganan sesuai jadwal.
• Jangan pernah menyimpan data sensitif di payload. JWT dikodekan, bukan dienkripsi.

OAuth2

• Gunakan alur Kode Otorisasi dengan PKCE untuk semua klien, termasuk SPA dan seluler aplikasi.
• Jangan pernah menggunakan aliran Implisit. Ini tidak digunakan lagi di OAuth 2.1 karena alasan yang bagus.
• Simpan rahasia klien di server saja. Jangan pernah mengirimkannya dalam aplikasi seluler atau frontend kode.
• Mengesahkan state parameter untuk mencegah serangan CSRF pada URL panggilan balik.
• Gunakan token akses berumur pendek dengan rotasi token penyegaran.

Poin-poin penting

• Kunci API adalah pilihan tepat untuk API utilitas server-ke-server. Mereka cepat untuk diintegrasikan, mudah dikelola, dan memadai ketika tidak diperlukan identitas pengguna. botoi menggunakannya di 150+ titik akhir dengan Unkey untuk manajemen.
• JWT adalah pilihan yang tepat untuk sesi pengguna tanpa kewarganegaraan. Mereka menghilangkan pencarian penyimpanan sesi dalam skala tinggi, tetapi pencabutan token memerlukan infrastruktur tambahan.
• OAuth2 adalah pilihan yang tepat ketika aplikasi pihak ketiga memerlukan akses terbatas sumber daya pengguna. Kompleksitasnya dibenarkan oleh model keamanan yang disediakannya.
• Pilih berdasarkan penelepon, bukan hype. API utilitas dengan OAuth2 direkayasa secara berlebihan. SEBUAH platform API yang hanya memiliki kunci API tidak dapat memberikan akses yang didelegasikan.
• Gabungkan pendekatan ketika produk Anda membutuhkannya. Kunci API untuk integrasi langsung, OAuth2 untuk mitra pasar, JWT untuk sesi pengguna yang masuk.