Autentikasi & key

Setiap request ke API kenari diautentikasi dengan satu API key yang diawali kn-. Satu key berlaku untuk semua model, semua provider, dan kedua API (gaya OpenAI maupun gaya Anthropic).

API key kn-

API key dibuat di dashboard pada halaman API keys. Key diawali kn- dan hanya ditampilkan sekali saat dibuat. Setelah itu yang tersimpan hanya hash SHA-256-nya, jadi nilai aslinya tidak bisa dilihat lagi. Salin dan simpan di tempat aman begitu key pertama kali muncul.

Tidak perlu key terpisah per model atau per provider. Satu key kn- cukup untuk seluruh katalog dan untuk kedua format API.

Di terminal, jalankan npx @kenarihq/cli login untuk membuka halaman persetujuan di browser dan menyimpan key baru secara otomatis, tanpa perlu menyalin dan menempelkannya. Lihat CLI kenari.

Catatan Kalau key hilang, kamu tidak bisa memulihkannya. Buat key baru di dashboard lalu cabut yang lama.

Header Authorization

Kirim key lewat header Authorization dengan skema Bearer:

curl https://kenari.id/v1/chat/completions \
  -H "Authorization: Bearer kn-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "step-3-7-flash",
    "messages": [{"role": "user", "content": "Halo"}]
  }'

Memanggil dari browser (CORS)

API /v1 bisa dipanggil langsung dari JavaScript di browser. kenari mengirim header CORS pada rute /v1, jadi fetch dari halaman web berjalan tanpa proxy sendiri. Kamu juga bisa mengarahkan alat browser yang menerima URL API kustom ke https://kenari.id/v1.

const res = await fetch("https://kenari.id/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: "Bearer kn-...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "step-3-7-flash",
    messages: [{ role: "user", content: "Halo" }],
  }),
});
const data = await res.json();
console.log(data.choices[0].message.content);

Server menerima request preflight OPTIONS pada /v1 dengan header apa pun, jadi authorization, content-type, x-api-key, dan header Anthropic semuanya lolos. Kredensial (cookie) tidak diizinkan. /v1 hanya mengautentikasi lewat header Authorization: Bearer kn-... atau x-api-key.

Perhatian Key yang dipanggil dari browser terlihat oleh siapa pun yang membuka devtools. Ini cocok untuk alat lokal, proyek pribadi, dan prototipe. Aplikasi web produksi sebaiknya menyimpan key di server dan memanggil kenari dari sana.

API dashboard di bawah /api tetap tertutup untuk request lintas origin. Hanya /v1 yang terbuka untuk browser.

Endpoint yang butuh key

Endpoint berikut menolak request tanpa key yang valid:

Endpoint	Butuh key
POST /v1/chat/completions	Ya
POST /v1/messages	Ya
POST /v1/images/generations	Ya
GET /v1/account/quota	Ya
GET /v1/models	Tidak

GET /v1/models bersifat publik dan bisa dipanggil tanpa key. Kalau dipanggil dengan admin key, response menyertakan field internal tambahan.

GET /v1/account/quota juga menolak key yang dibagikan dengan HTTP 403 (shared_key_not_allowed).

Lihat Chat completions, Messages, dan Images untuk detail tiap endpoint.

Key salah atau hilang

Kalau key tidak ada atau salah, server membalas HTTP 401. Body-nya berupa teks biasa, bukan JSON, karena request ditolak sebelum mencapai lapisan API. Untuk format error pada kesalahan lain, lihat Errors.

Mengelola key

Di dashboard kamu bisa membuat, melihat, dan mencabut beberapa key sekaligus. Beri label tiap key agar mudah dibedakan, misalnya satu key per aplikasi, supaya satu key bisa dicabut tanpa mengganggu yang lain.

Pencabutan key langsung berlaku. Request berikutnya yang memakai key yang sudah dicabut akan ditolak dengan HTTP 401.

Pengecekan status akun

Status akun dicek pada setiap request. Akun yang ditangguhkan (suspended) membuat semua key miliknya berhenti bekerja seketika di semua tempat, terlepas dari apakah key itu sendiri masih aktif.

Perhatian Penangguhan akun langsung menghentikan seluruh pemakaian API dan tidak bisa dilewati dengan membuat key baru.

BYOK berbeda dari ini

Key kn- di halaman ini milik kenari dan dipakai untuk autentikasi ke gateway. Ini berbeda dari BYOK, yaitu key provider milikmu sendiri (misalnya key OpenAI atau Anthropic) yang kamu tautkan agar kenari memakainya untuk request kamu. Lihat BYOK.