Key per tool

Buat, lihat, dan cabut key per tool. Key per tool adalah key kenari biasa yang dimiliki satu tool di satu mesin, misalnya OpenCode di laptopmu. Kalau konfigurasi satu tool bocor, kamu cukup mencabut key itu dan yang lain tetap berjalan. Endpoint ini khusus kenari dan tidak punya padanan di OpenAI maupun Anthropic.

POST /v1/account/keys, GET /v1/account/keys, dan DELETE /v1/account/keys/{id}

Siapa yang bisa memanggil

Hanya key yang disimpan oleh kenari login yang bisa mengelola key per tool. Lihat CLI kenari. Key lain mendapat 403 dan cli_login_key_required, termasuk:

• Key yang kamu buat di API Keys pada dashboard, dan key dari kenari login --api-key.
• Key per tool. Sebuah tool tidak bisa membuat key tambahan untuk dirinya sendiri.
• Key dari kenari login yang kamu buat sebelum key per tool ada. Jalankan kenari login lagi untuk mendapat key yang bisa dipakai.

API key dibagikan mendapat shared_key_not_allowed, dan key yang dibatasi mendapat restricted_key_not_allowed. Key dibatasi kalau punya pembatasan model, batas biaya, atau batas token. Lihat Ringkasan akun.

Setiap panggilan membutuhkan key di header Authorization sebagai Bearer kn-....

Buat key

POST /v1/account/keys membuat key di bawah key yang kamu pakai untuk memanggilnya.

Field	Tipe	Wajib	Keterangan
tool	string	Ya	Tool yang memakai key, misalnya opencode. 1 sampai 40 karakter dari a-z, 0-9, ., dan -.
host	string	Ya	Mesin tempat tool berjalan, misalnya laptop. 1 sampai 64 karakter dari A-Z, a-z, 0-9, ., _, dan -.

Response-nya 201 berisi key baru:

{
  "id": "e72755dd-ea6b-4d93-9e96-eb4c817824d0",
  "key": "kn-984e1408144f2e604c38d27e6596638ec57882ad022a4fdd",
  "prefix": "kn-984e1408",
  "label": "kenari-cli · opencode · laptop",
  "created_at": 1790000000
}

Field	Tipe	Keterangan
id	string	Id yang dipakai saat mencabut key.
key	string	Key lengkap. Hanya ditampilkan sekali, jadi simpan sekarang.
prefix	string	Beberapa karakter pertama key, untuk membedakan key.
label	string	kenari-cli · <tool> · <host>. Label yang sama tampil di samping key pada API Keys di dashboard.
created_at	integer	Waktu key dibuat, dalam detik sejak Unix epoch.

Key per tool bekerja seperti key asalnya untuk semua model dan endpoint, kecuali tidak bisa mengelola key. Penagihannya sama dengan key kamu yang lain.

Lihat key

GET /v1/account/keys tidak menerima parameter. Endpoint ini mengembalikan key per tool yang aktif milik key yang kamu pakai untuk memanggilnya, dari yang terbaru. Key yang sudah dicabut tidak ditampilkan, dan key lengkap tidak pernah dikembalikan lagi.

{
  "object": "list",
  "data": [
    {
      "id": "e72755dd-ea6b-4d93-9e96-eb4c817824d0",
      "prefix": "kn-984e1408",
      "label": "kenari-cli · opencode · laptop",
      "created_at": 1790000000,
      "last_used_at": 1790003600
    }
  ]
}

last_used_at adalah waktu terakhir key dipakai untuk request, dalam detik sejak Unix epoch. Nilainya null bila tidak ada pemakaian yang tercatat dalam 90 hari terakhir.

Cabut key

DELETE /v1/account/keys/{id} mencabut satu key per tool secara permanen. Request berikutnya yang memakainya mendapat 401.

{
  "id": "e72755dd-ea6b-4d93-9e96-eb4c817824d0",
  "revoked": true
}

id harus milik key per tool dari key yang kamu pakai untuk memanggil. Id lain mengembalikan 404 dan not_found, baik key tidak ada, sudah dicabut, maupun milik orang lain.

Batas

• Satu key login bisa memegang 30 key per tool yang aktif. Cabut satu untuk membuat yang baru.
• Key per tool dihitung dalam batas key akunmu, sama seperti key lain.
• Setiap key login bisa membuat 20 key per menit.

Mencabut key login

Saat kamu mencabut key dari kenari login di API Keys pada dashboard, semua key per tool miliknya ikut dicabut. Mencabut satu key per tool tidak memengaruhi key login maupun key per tool lainnya. Lihat Autentikasi & API key.

Contoh

curl

# Buat key
curl https://kenari.id/v1/account/keys \
  -H "Authorization: Bearer $KENARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "opencode",
    "host": "laptop"
  }'

# Lihat key
curl https://kenari.id/v1/account/keys \
  -H "Authorization: Bearer $KENARI_API_KEY"

# Cabut key
curl -X DELETE https://kenari.id/v1/account/keys/e72755dd-ea6b-4d93-9e96-eb4c817824d0 \
  -H "Authorization: Bearer $KENARI_API_KEY"

Di sini $KENARI_API_KEY adalah key dari kenari login.

Python

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['KENARI_API_KEY']}"}

created = requests.post(
    "https://kenari.id/v1/account/keys",
    headers=headers,
    json={"tool": "opencode", "host": "laptop"},
)
created.raise_for_status()
tool_key = created.json()
print(tool_key["label"])

requests.delete(
    f"https://kenari.id/v1/account/keys/{tool_key['id']}",
    headers=headers,
).raise_for_status()

JavaScript

const headers = { Authorization: `Bearer ${process.env.KENARI_API_KEY}` };

const created = await fetch("https://kenari.id/v1/account/keys", {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ tool: "opencode", host: "laptop" }),
});
if (!created.ok) throw new Error(await created.text());
const toolKey = await created.json();
console.log(toolKey.label);

const revoked = await fetch(`https://kenari.id/v1/account/keys/${toolKey.id}`, {
  method: "DELETE",
  headers,
});
if (!revoked.ok) throw new Error(await revoked.text());

Penagihan

Membuat, melihat, dan mencabut key tidak dikenai biaya. Request yang memakai key per tool ditagih seperti request lain. Lihat Cara penagihan.

Error

Status	Kode	Kapan
400	bad_request	Body bukan JSON dengan field string tool dan host, atau salah satunya memuat karakter atau panjang yang tidak diizinkan. Juga saat akunmu sudah mencapai batas key, dengan pesan key limit reached.
401	Tidak ada	Key tidak ada, tidak valid, sudah dicabut, atau sudah kedaluwarsa. Body-nya pesan teks singkat, bukan JSON.
403	cli_login_key_required	Key bukan key dari kenari login.
403	shared_key_not_allowed	Key adalah API key dibagikan.
403	restricted_key_not_allowed	Key punya pembatasan model, batas biaya, atau batas token.
404	not_found	Saat mencabut, id bukan key per tool yang aktif milik key yang kamu pakai.
409	child_key_cap	Saat membuat, key login sudah memegang 30 key per tool yang aktif.
429	rate_limit_exceeded	Saat membuat, lebih dari 20 request dalam satu menit. Tidak ada header Retry-After. Tunggu beberapa detik lalu coba lagi.
500	internal_error	Ada yang gagal di kenari. Coba lagi sekali.

Lihat Error untuk format error dan kode lainnya.

Lihat juga

• Ringkasan akun
• CLI kenari
• Autentikasi & API key
• Error