Lewati ke konten
KoboiLLM Docs

API Manajemen Tim

Jika Anda mengelola sebuah Tim di KoboiLLM, Anda akan diberikan sebuah Team Management Key (API Key Admin Tim). Key ini memberikan wewenang penuh kepada Anda untuk mengelola seluruh resources di dalam tim Anda sendiri secara terprogram—seperti memantau sisa saldo, menarik laporan transaksi, mengundang anggota, hingga membuat Virtual Key baru secara otomatis dari dalam aplikasi Anda sendiri.

Parameter Utama Integrasi

  • Management Base URL: https://api.koboillm.com (Gunakan domain utama gateway).
  • Authorization Header: Kirimkan Management Key Anda sebagai Bearer token: 
    Authorization: Bearer sk-xxx...xxxx
  • Team ID Anda: Buka dashboard tim Anda untuk menyalin ID unik tim Anda (contoh: team_99c03b...).

1. Mengambil Informasi Saldo & Budget Tim

Endpoint ini adalah jantung dari integrasi manajemen keuangan tim Anda. Anda dapat menggunakannya untuk menampilkan budget maksimal, sisa saldo harian, dan ringkasan penggunaan token tim di dashboard aplikasi Anda sendiri.

  • Method & Route: GET /team/info
  • Query Parameters:
    • team_id (string, required): ID unik tim Anda.

Contoh Request (cURL):

Terminal window
curl -X GET "https://api.koboillm.com/team/info?team_id=your-team-id" \
     -H "Authorization: Bearer sk-your-management-key" \
     -H "accept: application/json"

Contoh Response JSON:

{
  "team_info": {
    "team_id": "team_99c03b41-f761-463d-8ab1-16b0b471ec1b",
    "team_alias": "Grosir Kaos Kaki",
    "spend": 15.4306,
    "max_budget": 100.00,
    "budget_duration": "30d",
    "budget_reset_at": "2026-08-01T00:00:00Z"
  },
  "keys": [
    {
      "key_name": "Editor Key 1",
      "key_alias": "editor_key",
      "spend": 12.0450,
      "max_budget": 50.00,
      "last_active": "2026-07-16T15:45:20Z"
    },
    {
      "key_name": "Test Key",
      "key_alias": "test_key",
      "spend": 3.3856,
      "max_budget": 10.00,
      "last_active": "2026-07-16T12:10:05Z"
    }
  ]
}

2. Membuat Virtual Key Baru secara Otomatis

Jika aplikasi Anda memerlukan pembuatan API Key baru secara otomatis untuk setiap user, customer, atau sub-agent, Anda dapat melakukannya langsung dari backend program Anda.

  • Method & Route: POST /key/generate
  • Headers:
    • Content-Type: application/json

Payload Parameter (JSON):

  • team_id (string, required): Harus diisi dengan ID tim Anda agar key baru terdaftar di tim Anda.
  • key_alias (string, optional): Nama penanda untuk mempermudah identifikasi key.
  • max_budget (float, optional): Limit saldo khusus untuk key ini (dalam USD).
  • budget_duration (string, optional): Masa berlaku limit, misalnya 30d (30 hari), 24h (24 jam), atau 7d (7 hari).

Contoh Request (Python):

import requests


url = "https://api.koboillm.com/key/generate"
headers = {
    "Authorization": "Bearer sk-your-management-key",
    "Content-Type": "application/json"
}
payload = {
    "team_id": "your-team-id",
    "key_alias": "customer_kaos_kaki_142",
    "max_budget": 5.00,
    "budget_duration": "30d"
}


response = requests.post(url, headers=headers, json=payload)
print(response.json())

Contoh Response JSON:

{
  "key": "sk-koboillm-a1b2c3d4e5f6g7h8i9j0...",
  "token": "a1b2c3d4e5f6g7h8i9j0...",
  "key_alias": "customer_kaos_kaki_142",
  "max_budget": 5.00,
  "spend": 0.0,
  "team_id": "your-team-id"
}

Satu Kali Tampil

Nilai "key" (dimulai dengan sk-koboillm-...) hanya akan muncul satu kali pada response pembuatan pertama. Pastikan aplikasi Anda langsung menyimpan token tersebut dengan aman ke database Anda.

3. Memblokir & Membuka Blokir Virtual Key

Jika customer Anda kehabisan paket atau melanggar ketentuan layanan, Anda dapat menonaktifkan API Key mereka secara instan dari aplikasi Anda.

Memblokir Key (Suspending)

  • Method & Route: POST /key/block
  • Payload JSON: 
    { "key": "sk-koboillm-key_to_block_here" }

Membuka Blokir Key (Unblocking)

  • Method & Route: POST /key/unblock
  • Payload JSON: 
    { "key": "sk-koboillm-key_to_unblock_here" }

4. Mengambil Riwayat Transaksi & Detil Log Tim

Anda dapat menarik data log transaksi real-time dari semua request yang dilakukan oleh seluruh anggota atau Virtual Key di dalam tim Anda. Data ini sangat berguna untuk menampilkan grafik aktivitas atau melakukan debugging.

  • Method & Route: GET /spend/logs
  • Query Parameters:
    • team_id (string, required): ID tim Anda.
    • limit (integer, optional): Jumlah log maksimal per request (default: 50, max: 100).

Contoh Request (cURL):

Terminal window
curl -X GET "https://api.koboillm.com/spend/logs?team_id=your-team-id&limit=10" \
     -H "Authorization: Bearer sk-your-management-key"

Informasi Berharga di dalam Log:

Setiap baris log transaksi mengembalikan data berharga berikut:

  • spend (float): Biaya riil request tersebut dalam USD.
  • model (string): Model yang digunakan (misalnya openai/gpt-5.6-terra).
  • total_tokens (integer): Total token yang diproses.
  • metadata->>'key_alias' (string): Nama key yang melakukan request, mempermudah Anda melakukan audit per-customer.

5. Mengelola Anggota Tim (Team Member Directory)

Anda dapat menambah developer atau anggota tim lain agar dapat masuk dan memantau dashboard tim bersama-sama.

Mengundang Anggota Baru:

  • Method & Route: POST /team/member_add
  • Payload JSON: 
    {
      "team_id": "your-team-id",
      "member_email": "developer@perusahaan.com",
      "role": "user" // Peran: "user" (view only) atau "admin" (management)
    }

Mengeluarkan Anggota:

  • Method & Route: POST /team/member_delete
  • Payload JSON: 
    {
      "team_id": "your-team-id",
      "member_email": "stale-developer@perusahaan.com"
    }

6. Operasi Lanjutan Virtual Key (Info, Update, Rotate, Reset, & Delete)

Selain pembuatan dasar, Team Management Key Anda mendukung kontrol lifecycle penuh dari setiap Virtual Key di dalam tim Anda.

A. Mendapatkan Informasi Spesifik Key (GET /key/info)

Mengambil info metadata, sisa limit, rate limit, dan last active timestamp dari satu key tertentu.

  • Method & Route: GET /key/info
  • Query Parameters:
    • key (string, required): Virtual Key yang ingin diperiksa (contoh: sk-kob...).
Terminal window
curl -X GET "https://api.koboillm.com/key/info?key=sk-koboillm-your-key-here" \
     -H "Authorization: Bearer *** \
     -H "accept: application/json"

Struktur Response JSON Lengkap:

{
  "key": "sk-koboillm-your-key-here",
  "info": {
    "token": "a1b2c3d4e5f6g7h8i9j0...",
    "key_name": "Editor Key 1",
    "key_alias": "editor_key",
    "spend": 12.0450,
    "max_budget": 50.00,
    "budget_duration": "30d",
    "budget_reset_at": "2026-08-01T00:00:00Z",
    "last_active": "2026-07-16T15:45:20Z",
    "user_id": "user_12345",
    "team_id": "team_99c03b41-f761-463d-8ab1-16b0b471ec1b",
    "tpm_limit": 50000,
    "rpm_limit": 100,
    "blocked": false,
    "models": ["openai/gpt-5.6-luna", "openai/gpt-5.6-terra"],
    "created_at": "2026-07-08T11:27:28Z"
  }
}

Penjelasan Setiap Field Response:

  • token (string): Nilai hash/samaran unik dari database yang memetakan Virtual Key ini. Demi alasan keamanan tingkat tinggi, token kunci asli yang digunakan untuk memanggil API (sk-...) tidak akan pernah disimpan secara plaintext di database maupun diekspos utuh dalam respons detail ini.
  • key_name / key_alias (string): Nama panggilan atau alias penanda Virtual Key yang Anda masukkan saat pembuatan guna mempermudah pengelompokan (misalnya penanda ID per-customer/user di database aplikasi Anda).
  • spend (float): Jumlah akumulasi biaya riil (dalam USD) yang telah dihabiskan dan diproses khusus oleh Virtual Key ini sepanjang siklus masa berlakunya.
  • max_budget (float): Batas anggaran pengeluaran maksimal (dalam USD) yang diizinkan untuk dihabiskan oleh Virtual Key ini. Jika spend mencapai atau melewati nilai ini, pemanggilan API selanjutnya menggunakan key ini akan ditolak secara otomatis oleh gateway.
  • budget_duration (string): Siklus atau durasi otomatisasi reset budget (misalnya 30d untuk bulanan, 7d untuk mingguan, atau 24h untuk harian). Jika bernilai null, berarti budget bersifat flat tanpa reset berkala sepanjang masa berlaku kunci.
  • budget_reset_at (string): ISO timestamp kapan penghitung spend (penggunaan) dari Virtual Key ini akan otomatis direset kembali ke $0.00 berdasarkan aturan budget_duration.
  • last_active (string): ISO timestamp kapan Virtual Key ini terakhir kali sukses digunakan untuk memproses request API dari client. Sangat berguna untuk memantau status keaktifan user Anda.
  • user_id (string): ID unik milik konsumen atau sistem eksternal yang dikaitkan sebagai penanggung jawab Virtual Key tersebut.
  • team_id (string): ID unik tim KoboiLLM tempat Virtual Key ini bernaung (selalu terisolasi dan berada di bawah naungan ID tim Anda sendiri).
  • tpm_limit (integer): Batas throughput Tokens per Minute (TPM) yang diizinkan untuk kunci ini. Membatasi volume kata/token maksimal yang boleh diproses dalam periode 60 detik.
  • rpm_limit (integer): Batas frekuensi Requests per Minute (RPM) yang diizinkan untuk kunci ini. Membatasi volume jumlah pemanggilan API maksimal dalam periode 60 detik.
  • blocked (boolean): Indikator status penangguhan kunci. Jika bernilai true, semua pemanggilan API menggunakan key ini akan ditolak seketika oleh gateway.
  • models (array): Daftar nama-nama model AI tertentu (whitelist) yang diizinkan untuk dipanggil oleh Virtual Key ini. Jika berupa array kosong [], berarti key ini mewarisi hak akses semua model default yang diizinkan pada tim Anda.
  • created_at (string): ISO timestamp kapan Virtual Key ini pertama kali dibuat oleh sistem.

B. Mengupdate Parameter Key (POST /key/update)

Mengubah metadata, rate-limit, atau memodifikasi budget pada key yang sedang aktif.

  • Method & Route: POST /key/update
  • Payload JSON: 
    {
      "key": "sk-koboillm-your-key-here",
      "key_alias": "nama_alias_baru",
      "max_budget": 15.00, // Menaikkan limit saldo key
      "budget_duration": "7d", // Mengubah masa berlaku budget harian/mingguan
      "tpm_limit": 50000, // Batasan Token per Menit (Optional)
      "rpm_limit": 100 // Batasan Request per Menit (Optional)
    }

C. Melakukan Rotasi Key / Regenerate (POST /key/regenerate)

Menghapus key lama dan menggantinya dengan token key baru, sambil otomatis mewarisi seluruh riwayat spend, limit, dan parameter konfigurasi sebelumnya. Sangat berguna untuk skema security key-rotation berkala.

  • Method & Route: POST /key/regenerate
  • Payload JSON: 
    {
      "key": "sk-koboillm-stale-key-here"
    }
  • Response JSON: Mengembalikan string "key" baru yang harus langsung Anda simpan.

D. Mereset Akumulasi Pengeluaran Key (POST /key/{key}/reset_spend)

Mereset penghitung pengeluaran (spend) suatu Virtual Key kembali ke $0.00 tanpa mengubah budget limit atau menghapus key tersebut.

  • Method & Route: POST /key/sk-koboillm-your-key-here/reset_spend
Terminal window
curl -X POST "https://api.koboillm.com/key/sk-koboillm-your-key-here/reset_spend" \
     -H "Authorization: Bearer ***

E. Menghapus Key Permanen (POST /key/delete)

Menghapus Virtual Key secara permanen dari sistem KoboiLLM. Seluruh request yang mencoba menggunakan key ini setelahnya akan ditolak seketika (401 Unauthorized).

  • Method & Route: POST /key/delete
  • Payload JSON: 
    {
      "key": "sk-koboillm-trash-key-here"
    }

7. Kontrol Keamanan & Callback Integrasi Tim

Anda dapat mengelola model apa saja yang diizinkan untuk diakses tim Anda, serta menghubungkan webhook callback otomatis untuk alerting.

A. Membatasi Model Akses Tim (POST /team/model/add & /team/model/delete)

Secara default, tim Anda dapat mengakses semua model. Jika Anda ingin membatasi agar anggota tim Anda hanya boleh memanggil model hemat (misalnya hanya openai/gpt-5.6-luna), Anda dapat mengaturnya secara terprogram.

Menambahkan Model yang Diizinkan (Whitelist):

  • Method & Route: POST /team/model/add
  • Payload JSON: 
    {
      "team_id": "your-team-id",
      "models": ["openai/gpt-5.6-luna", "openai/gpt-5.6-terra"]
    }

Menghapus Izin Model:

  • Method & Route: POST /team/model/delete
  • Payload JSON: 
    {
      "team_id": "your-team-id",
      "models": ["openai/gpt-5.6-sol"]
    }

B. Mendaftarkan Webhook Callback Otomatis (POST /team/{team_id}/callback)

Anda dapat mendaftarkan URL endpoint webhook server milik Anda sendiri. KoboiLLM akan secara otomatis mengirimkan payload callback HTTP POST real-time setiap kali ada transaksi diselesaikan, atau memberikan alert otomatis saat saldo tim berada di bawah ambang batas kritis (low budget alert).

  • Method & Route: POST /team/your-team-id/callback
  • Payload JSON: 
    {
      "callbacks": [
        {
          "callback_type": "webhook",
          "url": "https://api.perusahaan-anda.com/koboy-billing-alerts",
          "headers": {
            "X-Custom-Secret": "your-webhook-verification-token"
          }
        }
      ]
    }

C. Menyetel Fitur Privasi Ketat / Disable Logging (POST /team/{team_id}/disable_logging)

Untuk industri dengan kepatuhan privasi data yang tinggi, Anda dapat menginstruksikan KoboiLLM untuk tidak mencatatkan/menyimpan isi konten chat (prompt & completions) dari tim Anda ke database logs proxy. Server hanya akan mencatat metadata transaksi (token, biaya, model) untuk keperluan billing.

  • Method & Route: POST /team/your-team-id/disable_logging

8. Analisis Statistik Aktivitas Harian Tim (GET /team/daily/activity)

Mengambil data analitik agregat harian (grafik Token per Menit, volume Request per Menit, serta total pengeluaran kumulatif harian) khusus untuk tim Anda. Sangat ideal untuk direndering menjadi visual grafik di dashboard aplikasi Anda.

  • Method & Route: GET /team/daily/activity
  • Query Parameters:
    • team_id (string, required): ID unik tim Anda.

Contoh Request:

Terminal window
curl -X GET "https://api.koboillm.com/team/daily/activity?team_id=your-team-id" \
     -H "Authorization: Bearer *** \
     -H "accept: application/json"

Contoh Response JSON:

[
  {
    "date": "2026-07-16",
    "total_spend": 12.4560,
    "total_tokens": 45120800,
    "total_requests": 8410
  },
  {
    "date": "2026-07-15",
    "total_spend": 2.9746,
    "total_tokens": 12050900,
    "total_requests": 2517
  }
]

Tanya Jawab & Kendala Umum

Q: Mengapa saya mendapatkan error 401 Unauthorized?

  • Periksa kembali apakah Management Key Anda dikirim utuh pada Authorization Header dengan format Bearer <token>.
  • Pastikan token management key belum expired atau diblokir oleh admin utama KoboiLLM.

Q: Mengapa saya mendapatkan error 403 Forbidden saat mencoba memanggil /team/new?

  • Itu adalah batasan keamanan yang didesain secara sengaja. Team Management Key tidak memiliki wewenang untuk membuat tim baru di tingkat proxy global atau mengutak-atik tim lain. Hubungi admin utama KoboiLLM jika Anda memerlukan pembuatan space tim tambahan.

Q: Apakah ada limit pembuatan Virtual Key di dalam tim?

  • Secara default tidak ada batasan jumlah key harian, namun pastikan setelan budget total key yang dibuat berada di bawah total max_budget tim Anda guna menghindari kegagalan request akibat limit overspend.