Autentikasi

Cara memakai kunci API Hostlinku, masa berlaku kunci, limit kredit per kunci, dan praktik keamanannya

Gateway Hostlinku memakai autentikasi Bearer token dengan kunci API berformat sk-…. Sertakan kunci pada setiap request ke endpoint /v1/*:

Authorization: Bearer sk-isi-kunci-anda
Content-Type: application/json

Kunci dibuat dan dikelola di console.hostlinku.com → menu Kunci API.

Membuat kunci

Buka console → Kunci API → Buat Kunci.
Isi Nama, opsional Kedaluwarsa, dan opsional Limit kredit.
Salin secret yang ditampilkan. Secret hanya muncul sekali.

Kunci disimpan server dalam bentuk hash SHA-256 — nilai aslinya tidak pernah tersimpan dan tidak bisa ditampilkan ulang. Kunci lama yang pernah dibuat dengan format legacy (hl_live_…) tetap berfungsi: autentikasi mencari berdasarkan hash, bukan berdasarkan prefix.

Masa berlaku kunci

Kedaluwarsa bersifat opsional saat pembuatan kunci:

Pilihan	Perilaku
Tidak pernah	Kunci berlaku sampai di-revoke
30 / 90 / 365 hari	Kunci berhenti berlaku otomatis setelah masa itu
Tanggal kustom	Kedaluwarsa pada tanggal yang dipilih

Kunci yang sudah lewat masa berlaku ditolak dengan:

{
  "status": "error",
  "error": { "code": "UNAUTHORIZED", "message": "API key sudah kedaluwarsa." }
}

Limit kredit per kunci

Setiap kunci bisa diberi batas pemakaian dalam USD (creditLimit) dengan jendela reset:

Reset	Jendela perhitungan (kalender UTC)
Harian (`daily`)	Sejak 00:00 UTC hari berjalan
Mingguan (`weekly`)	Sejak Senin 00:00 UTC minggu berjalan
Bulanan (`monthly`)	Sejak tanggal 1, 00:00 UTC bulan berjalan
Tanpa reset	Total selama kunci hidup

Pemakaian dihitung dari biaya request nyata (requests.customer_cost) yang tercatat untuk kunci tersebut. Saat biaya terakumulasi menyentuh limit, request berikutnya ditolak dengan 402 PAYMENT_REQUIRED:

{
  "status": "error",
  "error": {
    "code": "PAYMENT_REQUIRED",
    "message": "Limit kredit kunci tercapai ($10.0000 dari $10 total)."
  }
}

Limit kredit berbeda dari saldo akun: limit membatasi satu kunci, sedangkan saldo akun adalah sumber dana seluruh kunci. Keduanya harus cukup agar request berjalan. Lihat Billing & Saldo.

Rate limit

Di samping limit kredit, gateway menerapkan rate limit per kunci:

POST /v1/chat/completions — 600 request per menit per kunci API.
Endpoint konsol/public (sesi cookie) — 120 request per menit per alamat IP.
Endpoint autentikasi (login/daftar/reset) — 30 percobaan per 15 menit per IP.

Melebihi batas menghasilkan 429 RATE_LIMITED. Detailnya di Pemakaian & Limit.

Error autentikasi umum

Situasi	HTTP	`error.code`	Pesan
Header `Authorization` tidak ada atau bukan Bearer	401	`UNAUTHORIZED`	`Autentikasi diperlukan.`
Kunci tidak dikenal, salah ketik, atau sudah di-revoke	401	`UNAUTHORIZED`	`API key tidak valid atau sudah dicabut.`
Kunci sudah lewat masa berlaku	401	`UNAUTHORIZED`	`API key sudah kedaluwarsa.`
Kunci menabrak limit kreditnya	402	`PAYMENT_REQUIRED`	`Limit kredit kunci tercapai (…)`
Saldo akun tidak cukup untuk reservasi request	402	`PAYMENT_REQUIRED`	`Saldo kredit tidak cukup untuk request ini.`
Melampaui rate limit	429	`RATE_LIMITED`	`Rate limit terlampaui. …`

Keamanan kunci

Jangan menaruh kunci API di kode yang berjalan di browser/client-side atau di repositori publik.
Gunakan environment variable di server (mis. HOSTLINKU_API_KEY) dan baca dari situ.
Buat kunci terpisah per aplikasi/environment agar bisa di-revoke satu per satu tanpa mengganggu yang lain.
Manfaatkan kedaluwarsa dan limit kredit sebagai lapisan pertahanan kalau kunci bocor.
Kunci yang tidak dipakai lagi bisa di-revoke (dinonaktifkan, riwayat tetap ada) atau purge (dihapus permanen) dari console.

Rotasi kunci

Alur rotasi yang disarankan: buat kunci baru → pasang di aplikasi → verifikasi request sukses → revoke kunci lama. Tidak ada downtime karena kedua kunci aktif bersamaan.

Autentikasi

Membuat kunci

Masa berlaku kunci

Limit kredit per kunci

Rate limit

Error autentikasi umum

PRODUK

DOKUMENTASI

BANTUAN