API anahtarları

API anahtarı, bir eklentinin ya da dış aracın sitenizdeki belirli verilere erişmesini sağlayan gizli bir paroladır. Her anahtara yalnızca gereken kapsamları verirsiniz; böylece örneğin yalnızca mağaza kataloğunu okuyabilen bir anahtar kredi ekleyemez.

Yönetim panelinde nerede

Ayarlar → API Anahtarları (/admin/api-keys). Sayfa yalnızca tam yönetici hesabına açıktır. Üstte yeni anahtar formu, altta mevcut anahtarların listesi (ad, önek, kapsamlar, sunucu kilidi, son kullanım, durum) bulunur.

Anahtar oluşturma

Alan	Açıklama
Ad	Anahtarın ne için kullanıldığını hatırlatan ad, en fazla 60 karakter (örn. “Lobi eklentisi”). Zorunlu.
Sunucu kilidi	Tüm sunucular ya da tek bir oyun sunucusu. Bir sunucu seçerseniz anahtar o sunucuya bağlanır.
Kapsamlar	Anahtarın yapabileceği işler. En az bir kapsam seçmelisiniz.

Kapsamlar

Kapsam	Panelde görünen açıklama
`store.read`	Mağaza kataloğunu okuma
`store.buy`	Oyun içi satın alma (kredi ile)
`credits.read`	Kredi bakiyesi okuma
`credits.write`	Kredi ekleme, çıkarma, aktarma, bakiyeyi belirli bir değere ayarlama
`users.read`	Kullanıcı ve sipariş okuma
`roles.write`	Görünüm rolü atama (yetkili rol atanamaz)
`stats.write`	Oyun istatistiği gönderme
`link`	Hesap bağlama kodu üretme
`deliver`	Teslimat uçları
`console`	Konsol komutu kuyruğu
`support.read`	Destek taleplerini, kategorileri ve hazır yanıtları okur
`support.write`	Oyuncu adına destek talebi açar, mesaj yazar ve talebi kapatır
`players.session`	Oyun içi oturum durumunu sorgular. Yanıt bir hesabın var olup olmadığını ele verir; yalnız güvendiğiniz sunucuya verin

Formu doldurun
Ad yazın, gerekiyorsa Sunucu kilidini seçin ve yalnızca işinizin gerektirdiği kapsamları işaretleyin.
Anahtarı oluşturun
Anahtar oluştur’a basın. Ekranda anahtarın tamamı bir kez görünür ve kdr_ ile başlar.
Anahtarı kopyalayıp saklayın
Kopyala düğmesiyle anahtarı alın ve güvenli bir yere kaydedin. Kaydettim, gizle’ye bastığınızda anahtar bir daha gösterilmez.
Bağlantıyı deneyin
Aracınızda anahtarı kullanarak /api/v1/ping adresini çağırın. Yanıt, anahtarınızın adını, kapsamlarını ve sunucu kilidini döndürür; bu çağrı için kapsam gerekmez.

Anahtarı kullanma

Anahtar, isteğin başlığında gönderilir: Authorization: Bearer <anahtar> ya da X-API-KEY: <anahtar>. Adres satırında (URL içinde) gönderilmez; erişim kayıtlarına sızmaması için bu şekilde kabul edilmez.

Her anahtar dakikada en fazla 120 istek yapabilir. Kısa sürede bir IP adresinden çok sayıda yanlış anahtar denenirse o IP geçici olarak engellenir.

Destek talepleri

support.read ve support.write kapsamlı anahtarlar, oyuncu adına destek talebi yönetir. Oyuncu her istekte user alanıyla belirtilir: site kullanıcı kimliği, kullanıcı adı (ya da bağlı Minecraft adı) veya UUID. Talep açma, kategori ek alanları ve alan uzunlukları (konu 200, mesaj 5000 karakter) ile aktif talep sınırı, sitedeki destek formuyla aynı kurallardan geçer.

Uç	Kapsam	Açıklama
`GET /api/v1/support/tickets`	`support.read`	Oyuncunun talepleri. Sorgu: `user`, `status` (`OPEN`, `ANSWERED`, `CLOSED`), `page`, `limit` (en çok 50)
`GET /api/v1/support/tickets/{id}`	`support.read`	Talep ve mesajları (en çok 200 mesaj). `user` verilirse talep o oyuncunun değilse 404
`POST /api/v1/support/tickets`	`support.write`	Talep açar, 201 döner. Gövde: `user`, `subject`, `message`, isteğe bağlı `category`, `fieldValues`
`POST /api/v1/support/tickets/{id}/messages`	`support.write`	Talebe mesaj ekler. Gövde: `user`, `message`. Kapalı talepte 409
`POST /api/v1/support/tickets/{id}/close`	`support.write`	Talebi kapatır. Gövde: `user`
`GET /api/v1/support/categories`	`support.read`	Aktif kategoriler ve ek alan tanımları
`GET /api/v1/support/canned-responses`	`support.read`	Hazır yanıtlar

Destek ya da site kısıtı olan oyuncu adına talep açılamaz, mesaj yazılamaz (403).
Başkasının talebi 404 döner.
Oyuncu başına talep açma 10 dakikada en çok 5, mesaj yazma en çok 20 ile sınırlıdır; aşılırsa 429.
Yazan uçlarda Idempotency-Key başlığı isteğe bağlıdır ama yeniden denemelerde çift kayıt oluşmaması için önerilir.
Her yazma işlemi denetim kaydına API anahtarının adıyla düşer. Talep sahibinin e-postası hiçbir yanıtta dönmez.

POST /api/v1/support/tickets
{ "user": "Alex", "category": "odeme", "subject": "Siparişim gelmedi", "message": "Dün aldığım VIP gelmedi." }

Kullanıcı sorgusu

users.read kapsamlı anahtar GET /api/v1/users ile tek bir kullanıcıyı username, id, uuid ya da discord parametresinden biriyle sorgular. Parola, e-posta, iki adımlı doğrulama, oturum ve IP bilgisi hiçbir koşulda dönmez.

GET /api/v1/users?discord=<discord_kimligi> Discord hesabı bağlı site kullanıcısını döndürür:

discord yalnız rakamlardan oluşur ve 5 ile 25 hane arasındadır.
Yanıt, kullanıcının rollerini ve süreli rollerin bitiş tarihini (expiresAt, UTC ISO biçimi; süresizse null) da içerir.
Bu Discord kimliğine bağlı hesap yoksa 404 döner.

Kredi bakiyesini ayarlama

credits.write kapsamlı anahtar POST /api/v1/credits/set ile bakiyeyi mutlak bir değere ayarlar:

{ "username": "sunucum_oyuncu", "balance": 250, "reason": "Sayım düzeltmesi" }

balance: 0 ile 2.000.000.000 arasında tamsayı olmalıdır.
Farkı site hesaplar ve tek kredi hareketi olarak yazar.
Fark 0 ise hareket yazılmaz ve yanıtta changed: false döner.
Idempotency-Key başlığı isteğe bağlıdır ama önerilir.
Bakiye işlem sırasında başka bir yerden değişirse istek birkaç kez yeniden denenir; üst üste başarısız olursa 409 döner.

Oyun içi oturum durumu

Oyuncu oyuna girerken eklenti, POST /api/v1/players/session-status ile “bu oyuncunun sitede canlı oturumu var mı?” diye sorabilir. Uç players.session kapsamı ister.

Uç varsayılan olarak kapalıdır. Ayarlar → API Anahtarları sayfasındaki “Oyun içi oturum durumu ucu” bölümünden Oturum durumu ucunu etkinleştir kutusunu işaretleyerek açarsınız. Kapalıyken uç 403 döner.

POST /api/v1/players/session-status
{ "username": "Alex", "ip": "203.0.113.7", "userAgent": "Mozilla/5.0 ..." }

`status`	Anlamı
`register_required`	Sitede bu oyuncunun hesabı yok
`email_unverified`	E-posta doğrulaması zorunlu ve hesap doğrulanmamış
`login_required`	Hesap var, eşleşen canlı oturum yok
`two_factor_required`	Eşleşen oturum yok ve hesapta iki adımlı doğrulama açık
`session_active`	Aynı kullanıcıya ait, verdiğiniz IP ve User-Agent ile eşleşen canlı oturum var

session_active için ip ve userAgent alanlarının ikisi de verilmeli ve oturumdakiyle birebir aynı olmalıdır; biri eksikse bu durum hiçbir zaman dönmez. Yasaklı hesap için de dönmez. Site lisansı kilitliyken uç 423 döner.

Anahtarı iptal etme

Listedeki iptal düğmesi onay ister ve anahtarı kalıcı olarak geçersiz kılar: o anahtarı kullanan eklenti ve araçlar hemen erişimini kaybeder, işlem geri alınamaz. İptal edilen anahtar listede “İptal edildi” olarak kalır. Aynı anda en fazla 50 etkin anahtar olabilir; kullanmadıklarınızı iptal edin.

Minecraft eklentisinin kurulumu için Minecraft eklentisi sayfasına, oyun sunucularını tanımlamak için Oyun sunucuları sayfasına bakın.