Autentikasi & API key

Setiap endpoint /v1 kecuali GET /v1/models membutuhkan API key. Key diawali kn-, dan satu key berlaku untuk semua model dan semua format API.

Buat key

Buka API Keys di dashboard lalu pilih Buat API Key. Isi Label (opsional), misalnya nama aplikasi yang akan memakai key itu, supaya key mudah dibedakan dan satu key bisa dicabut tanpa mengganggu yang lain.

kenari hanya menampilkan key sekali, tepat setelah key dibuat. Key tidak bisa dipulihkan setelahnya. Kalau key hilang, pilih Putar key pada barisnya untuk mendapat key baru, atau buat key baru lalu cabut yang lama.

Kirim key

Kirim key lewat salah satu dari dua header. Keduanya berlaku di semua endpoint /v1.

Header	Dipakai oleh
`Authorization: Bearer kn-...`	SDK OpenAI dan sebagian besar klien HTTP
`x-api-key: kn-...`	SDK Anthropic dan Claude Code

Kalau request membawa kedua header, Authorization yang dipakai. Kirim key apa adanya di x-api-key, tanpa awalan Bearer.

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

Masuk dari terminal

CLI kenari bisa membuat dan menyimpan key untukmu. Pasang dengan npm install -g @kenarihq/cli, lalu jalankan kenari login. Browser terbuka untuk menyetujui login, lalu key baru tersimpan otomatis, jadi kamu tidak perlu menyalinnya. Di server tanpa browser, buat key di dashboard lalu jalankan kenari login --api-key. Perintah ini meminta key, atau membacanya dari stdin bila kamu mengalirkannya. Jangan pernah mengirim key sebagai argumen. Detailnya ada di panduan itu.

Panggil dari browser

API /v1 bisa dipanggil langsung dari JavaScript di browser, jadi fetch dari halaman web berjalan tanpa proxy sendiri.

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

/v1 menjawab request dari origin mana pun dan mengizinkan GET, POST, dan OPTIONS. Header request apa pun yang diminta browser saat preflight diterima, jadi Authorization, Content-Type, x-api-key, dan header Anthropic semuanya lolos. Cookie tidak dipakai: /v1 hanya membaca header Authorization atau x-api-key. Skrip bisa membaca header response x-request-id dan request-id. API dashboard di bawah /api tetap tertutup untuk request lintas origin.

Endpoint publik

Hanya GET /v1/models yang bisa dipanggil tanpa key di /v1. Endpoint berikut bersifat publik:

Endpoint	Fungsi
`GET /v1/models`	Daftar model, termasuk filter `?modality=`. Lihat Model & harga.
`GET /api/public/pricing`	Harga terkini dan batas tier gratis
`GET /openapi.json`	Deskripsi OpenAPI

Request tanpa key, atau dengan key yang salah, mendapat 401 dengan body teks biasa, bukan JSON. Lihat Error untuk pesannya.

Kelola dan cabut key

API Keys menampilkan semua key beserta statusnya, Aktif atau Dicabut. Pilih Cabut key untuk menonaktifkan key secara permanen. Key yang dicabut tidak bisa diaktifkan lagi, dan request berikutnya yang memakainya mendapat 401. Kalau kamu mencabut key yang disimpan kenari login, key per tool miliknya ikut dicabut. Putar key membuat key baru dan mencabut yang lama dalam satu langkah, jadi segera ganti key di aplikasimu.

kenari memeriksa status akun pada setiap request. Kalau akun ditangguhkan, semua key di akun itu berhenti bekerja seketika, dan membuat key baru tidak membantu.

Batasi key

Buka Pengaturan lanjutan (masa berlaku, cakupan model, kemampuan, batas biaya) di dialog pembuatan untuk mempersempit apa yang bisa dilakukan sebuah key.

Pengaturan	Fungsi
Masa berlaku	Key berhenti bekerja pada tanggal itu. Pilih Tanpa kedaluwarsa, jumlah hari, atau Kustom.
Cakupan model	Semua model, atau Model tertentu. Request untuk model lain gagal dengan `400` dan `bad_request`, dan pesannya mendaftar model yang diizinkan.
Kemampuan berbayar	Fitur berbayar mana yang boleh dipakai key: Pembacaan dokumen, Pencarian dan pengambilan halaman web, dan Pencarian X.
Batas biaya, Rp (opsional)	Pengeluaran maksimum key. Batas dihitung dari nilai pemakaian pada harga katalog, bukan dari jumlah saldo yang terpotong. Saat tercapai, request gagal dengan `402` dan `insufficient_balance`.

Daftar kemampuan bekerja seperti ini. Key tanpa pembatasan model bisa memakai semua kemampuan berbayar. Key dengan cakupan model hanya bisa memakai kemampuan yang kamu centang, dan request untuk kemampuan lain gagal dengan 400 dan bad_request, tanpa biaya. Pembacaan dokumen hanya mengatur OCR, yaitu engine ocr dan /v1/ocr. Key yang dibatasi tetap bisa melampirkan dokumen yang dibaca kenari dengan cara bawaan, karena itu hanyalah token input dari model yang boleh dipakainya. Lihat Baca dokumen dan Pencarian web & X.

Batas token (opsional), yaitu total token prompt dan hasil, diatur saat kamu membuat API key dibagikan.

Key dengan cakupan model, batas biaya, atau batas token tidak bisa memakai rute bernama. Key dengan batas biaya juga tidak bisa memakai model BYOK yang kamu panggil sebagai byok/..., dan request gagal dengan 403 dan byok_spend_capped_key. Batas biaya menghitung Rupiah yang dicatat kenari, sedangkan pemakaian BYOK tercatat Rp 0, jadi batasnya tidak akan pernah tercapai. Untuk membatasi pemakaian BYOK pada sebuah key, pakai batas token. Lihat BYOK.

Key terbatas juga hanya membaca pemakaian key-nya sendiri dari GET /v1/usage, dan GET /v1/account/balance serta GET /v1/account/quota menolaknya dengan 403 dan restricted_key_not_allowed. Lihat Ringkasan akun.

API key dibagikan

API key dibagikan memungkinkan orang lain memanggil kenari tanpa akun sendiri. Buka Bagikan, cari Bagikan API key, lalu pilih Buat share baru. Tentukan Model yang dibagikan, Masa berlaku (1-90 hari), dan kalau perlu batas biaya, batas token, catatan, serta kemampuan berbayar. Setelah itu pilih Buat Share. kenari membuat link publik dan sebuah key. Key itu hanya ditampilkan sekali, seperti key lainnya.

API key dibagikan memakai saldo atau kuota paketmu, hanya untuk model yang kamu pilih, dan berhenti pada tanggal berakhir atau saat batas tercapai. Kalau saldomu tidak cukup untuk sebuah request, pemegang key mendapat 402 dan insufficient_balance yang menunjuk ke kamu sebagai pemilik. Cabut share dari halaman yang sama dengan Cabut, dan link serta key langsung berhenti bekerja.

API key dibagikan adalah akses terbatas, jadi tidak bisa melakukan hal-hal ini:

Membaca data akunmu. GET /v1/account/balance, GET /v1/account/quota, dan endpoint Pemakaian menolak API key dibagikan dengan 403 dan shared_key_not_allowed, dan tool kenari_balance, kenari_usage, dan kenari_quota di Server MCP juga menolaknya. Lihat Kuota akun.
Memakai ulang hasil pembacaan dokumen yang dibayar key lain. Request gagal dengan 400 dan dokumen tidak dibaca. Mengunggah ulang dokumen yang sama tidak melewati batasan ini, karena hasil bacaan yang tersimpan tetap terikat pada key yang membayarnya. Lihat Baca dokumen.
Memakai rute bernama.

API key dibagikan juga punya pembatasan lajunya sendiri. Lihat Batas laju.