Kişisel API anahtarları: kapsamlar, IP listesi ve onay

Kişisel API anahtarları, kendi sunucundaki betiklerin ya da servislerin paket bilgilerini okumasına ve otomasyon görevlerini tetiklemesine olanak tanır. Anahtarlar tarayıcı oturumundan bağımsızdır; her anahtarın kapsamı, isteğe bağlı IP izin listesi ve geçerlilik süresi vardır. Bu rehberde anahtar oluşturmayı ve imzalı istekle jeton almayı anlatıyoruz.

Kapsamlar

Anahtar oluştururken yalnızca ihtiyacın olan kapsamları seç. Kapsam sonradan genişletilemez; daha fazla yetki gerekirse yeni bir anahtar oluşturman gerekir.

• read:account – kullanıcı adı, görünen ad, dil ve saat dilimini okur.
• read:subscriptions – paketlerini, durumlarını ve bitiş tarihlerini okur.
• read:automation – otomasyon görevlerini ve son çalışma sonuçlarını listeler.
• run:automation – otomasyon görevlerini elle tetikler. Yalnızca gerçekten gerekiyorsa ver.

Anahtar oluşturmak

1. Panelde API sayfasını aç ve yeni anahtar oluştur.
2. Anahtara bir ad ver (en fazla 40 karakter) ve kapsamları seç.
3. İstersen IP izin listesi ekle: tek adres (203.0.113.7) ya da aralık (203.0.113.0/24) biçiminde, en fazla 10 satır.
4. İstersen 1 ile 365 gün arasında bir geçerlilik süresi belirle.
5. Anahtar "Onay bekliyor" durumunda oluşturulur ve Telegram'a bir onay isteği gider. Botta Onayla'ya dokun.
6. Onaydan sonra gizli anahtarı (lbs_ ile başlar) panelde görüntüle ve hemen kaydet. Gizli anahtar yalnızca bir kez gösterilir.

Gizli anahtarı kopyalamadan pencereyi kapatırsan anahtarı iptal edip yenisini oluşturman gerekir. Hesap başına en fazla 10 etkin anahtar olabilir. Anahtarın adını ve IP listesini sonradan değiştirebilirsin; iptal ise anında geçerlidir ve açık jetonlar da hemen geçersiz olur.

İmzalı istekle jeton almak

Dış API'ye erişim iki adımlıdır. Önce anahtarınla imzalanmış bir POST isteğiyle 15 dakika geçerli bir erişim jetonu alırsın, ardından diğer uçları bu jetonla çağırırsın. Jeton isteğinde dört başlık gerekir: X-LB-Key (anahtar kimliği), X-LB-Timestamp (Unix saniye, en fazla 5 dakika sapma), X-LB-Nonce (16–64 karakter, her istekte yeni) ve X-LB-Signature.

İmza, gizli anahtarla HMAC-SHA256 kullanılarak şu metin üzerinden hesaplanır: zaman damgası, nonce, POST, /api/ext/v1/token ve gövdenin SHA-256 özeti; her biri ayrı satırda. Aşağıdaki örnek, panelde gösterilen örnekle aynı şemayı kullanır:

import { createHash, createHmac, randomBytes } from "node:crypto";

const KEY_ID = process.env.LB_KEY_ID;     // lbk_...
const SECRET = process.env.LB_KEY_SECRET; // lbs_...
const BASE = process.env.LB_API_BASE;     // Panel > API sayfasındaki adres (.../api/ext/v1)

async function getToken() {
  const body = "";
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const nonce = randomBytes(16).toString("hex");
  const bodyHash = createHash("sha256").update(body).digest("hex");
  const payload = `${timestamp}\n${nonce}\nPOST\n/api/ext/v1/token\n${bodyHash}`;
  const signature = createHmac("sha256", SECRET).update(payload).digest("hex");

  const res = await fetch(`${BASE}/token`, {
    method: "POST",
    headers: {
      "X-LB-Key": KEY_ID,
      "X-LB-Timestamp": timestamp,
      "X-LB-Nonce": nonce,
      "X-LB-Signature": signature,
    },
    body,
  });
  if (!res.ok) throw new Error(`Jeton alınamadı: ${res.status}`);
  const { accessToken } = await res.json();
  return accessToken;
}

const token = await getToken();
const res = await fetch(`${BASE}/subscriptions`, {
  headers: { Authorization: `Bearer ${token}` },
});
console.log(await res.json());

Jeton isteği reddedilirse yanıttaki mesaj nedeni belirtir: eksik ya da hatalı imza başlıkları, tutmayan imza, çok eski veya ileri tarihli zaman damgası, daha önce kullanılmış nonce, iptal edilmiş ya da süresi dolmuş anahtar veya izin listesinde olmayan bir IP adresi. Başarılı yanıtta erişim jetonu, geçerlilik süresi ve anahtarın kapsamları döner. Jetonun süresi dolduğunda aynı yöntemle yeni bir jeton alırsın.

Kullanılabilir uçlar

• POST /token – imzalı istekle 15 dakikalık erişim jetonu alır.
• GET /me – hesap bilgileri (read:account).
• GET /subscriptions – paketler ve bitiş tarihleri (read:subscriptions).
• GET /automation/tasks – otomasyon görevleri (read:automation).
• POST /automation/tasks/{id}/run – görevi hemen çalıştırır (run:automation).

Güvenlik önerileri

• Gizli anahtarı tarayıcıda çalışan koda koyma; yalnızca kendi sunucunda ya da betiklerinde, ortam değişkeninde sakla.
• Sabit IP'li bir sunucudan çağırıyorsan IP izin listesi ekle. Liste hem jeton alırken hem her istekte kontrol edilir.
• Her nonce yalnızca bir kez kabul edilir; yeniden oynatılan istekler reddedilir. Nonce'u her istekte rastgele üret.
• Sunucu saatini eşitle; 5 dakikadan fazla sapan zaman damgaları reddedilir.
• Anahtarları düzenli aralıklarla yenile: yeni anahtar oluştur, betiğini güncelle, eskisini iptal et.

Sonuç

Kişisel API anahtarları, en az yetki ilkesiyle kullanıldığında güvenli ve esnek bir entegrasyon yolu sunar. Oluşturma adımındaki Telegram onayı, hesabına erişen biri olsa bile senin haberin olmadan anahtar üretilmesini engeller. Hesap güvenliğinin diğer katmanları için passkey rehberine göz at.

API anahtarı oluştur