Başlarken/Kimlik doğrulama & imza

Kimlik doğrulama & imza

Operatör API istekleri ve cüzdan callback’leri aynı HMAC imzasını taşır. İmza; zaman damgasını, metodu, yolu, sorguyu ve ham gövdeyi kapsar. Böylece imzalı bir istek başka bir uç noktaya taşınamaz, 30 saniyeden sonra da tekrar oynatılamaz. Tek anahtarınız varsa iki yönde de onun secret’ı kullanılır; birden çoksa callback’ler imzalama anahtarıyla imzalanır (aşağıda).

Kimlik bilgileri

Bilgi	Açıklama
Operatör ID	Sabit kimliğiniz, örn. op_meridyen.
API anahtarı	Ortama göre önekli: Test (staging) pk_test_, Canlı (production) pk_live_. İlk Test anahtarı hesabınız açılınca kendiliğinden oluşur; Canlı anahtar production onayından sonra açılır. Birden çok anahtar açabilirsiniz. Siteye bağlı anahtar yalnız kendi sitesinde çalışır ve hesabınızda Boss Hub tarafından açılmalıdır.
İmza secret’ı	sk_ ile başlar. Yalnızca bir kez gösterilir: otomatik Test anahtarında ilk görüntülemede, diğerlerinde oluşturulurken. Kaybettiyseniz döndürün. Kod deposuna veya loglara yazmayın.
İmzalama anahtarı	Callback’ler o ortamın imzalama anahtarının secret’ıyla imzalanır: cüzdan ayarını ilk kaydettiğinizde etkin olan en yeni anahtar. Portalda bu anahtarın yanında İmzalıyor yazar. Her callback’teki X-Api-Key anahtarı söyler. İmzalama anahtarı, imzalama başka bir anahtara geçmeden iptal edilemez.

Kesintisiz anahtar yenileme

Callback’leri Boss Hub imzalar, siz doğrularsınız. İmzalama secret’ı sizin cüzdanınız yeni secret’ı tanımadan değişirse her bet, win, tekrar ve rollback INVALID_SIGNATURE alır, açık turlar takılır. Bu yüzden döndürme varsayılan olarak aşamalıdır; canlı trafik hiçbir adımda kesilmez:

Döndür deyin. Yeni anahtar ve secret bir kez gösterilir. Eski anahtar etkin kalır: API isteklerinizi doğrular ve callback’leri imzalamaya devam eder.
Yeni secret’ı API istemcinize ve cüzdanınıza kurun. Cüzdanınız iki secret’ı da tanısın; hangisiyle doğrulayacağını callback’teki X-Api-Key söyler.
Yeni anahtarın satırında İmzalamada kullan deyin. Callback’ler o andan sonra yeni secret’la imzalanır; bağlantı testi sıfırlanır, Bağlantıyı test et ile doğrulayın.
Trafiğin yeni secret’la geçtiğini görünce eski anahtarı İptal etin ve cüzdanınızdan eski secret’ı kaldırın.

Secret sızdıysa döndürürken Eski anahtarı hemen iptal et seçin: eski anahtar aynı anda iptal edilir, callback’ler hemen yeni secret’la imzalanır. Cüzdanınız yeni secret’ı kurana dek callback’ler INVALID_SIGNATURE alır; bu kipi yalnız acil durumda kullanın.

Başlıklar

Başlık	Açıklama
X-Operator-Id	Operatör kimliğiniz. Zorunlu.
X-Timestamp	Unix saniye. Zorunlu. ±30 sn dışı reddedilir.
X-Signature	İmza, küçük harf hex. Zorunlu.
X-Request-Id	API’de yazma isteklerinde (POST, PUT, DELETE) zorunlu, en çok 128 karakter. Callback’lerde her zaman vardır; bet, win ve rollback tekrarlarında aynı kalır.
X-Api-Key	İsteğe bağlı. Birden çok anahtarınız varsa doğru secret’ı seçer; gönderilmezse o ortamdaki aktif anahtarlar denenir.

İmza hesabı

hex(HMAC_SHA256(secret, ts + "." + METHOD + "." + path?query + "." + body))

ts: X-Timestamp başlığındaki değerin aynısı.
METHOD: büyük harfle HTTP metodu.
path?query: istek satırındaki hâliyle yol ve sorgu, /v1 dahil, kodlanmış biçimiyle. Callback’te kendi adresinizin taban yolu dahil tam yolu, örn. /bossgaming/bet.
body: ham gövde. Gövdesiz isteklerde boş metindir, imzalanan metin nokta ile biter.

Ham gövde: İmzayı gelen baytlar üzerinden doğrulayın. JSON’u ayrıştırıp yeniden yazarsanız 148.60 tutarı 148.6 olur ve imza tutmaz. Tutarları da float’a çevirmeden okuyun.

Diğer sayfalardaki kod örnekleri buradaki imzalama ve doğrulama yardımcılarını kullanır.

import { createHash, createHmac, timingSafeEqual } from 'node:crypto';

// Sign an outgoing request, or rebuild the signature of an incoming callback.
export function sign(secret, ts, method, pathWithQuery, rawBody = '') {
  return createHmac('sha256', secret)
    .update([ts, method.toUpperCase(), pathWithQuery, rawBody].join('.'))
    .digest('hex');
}

export const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');

// Express: keep the raw bytes with
// app.use(express.json({ verify: (req, _res, buf) => { req.rawBody = buf.toString('utf8'); } }))
export function verifySignature(req) {
  const ts = req.get('X-Timestamp') ?? '';
  if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 30) return false;
  const expected = sign(process.env.BOSS_SECRET, ts, req.method, req.originalUrl, req.rawBody ?? '');
  const given = (req.get('X-Signature') ?? '').toLowerCase();
  return given.length === expected.length
    && timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}

POSTÖrnek imza: callback

secret: sk_test_example

1762344000.POST./bossgaming/bet.{"transaction_id":"tx_01HF3K9QZ2YB","amount":2.00}

X-Signature: b0e89e3b7f1f07b0a54e36f262a5c5adb22dc556a8cd9cb41aac31e93adefb85

GETÖrnek imza: gövdesiz API isteği

secret: sk_test_example

1762344000.GET./v1/games?site_id=site_mrd01&lang=tr.

X-Signature: 8c020cb9d6b2c7688bde1a53987cf957b6ad9632d0f5f113866d3f9a45ec6906

Callback tekrarları

Boss Hub bir callback’i tekrar ettiğinde gövde bayt bayt aynıdır ve X-Request-Id değişmez; yalnız X-Timestamp ile X-Signature yenilenir. Tekrarı imzadan değil transaction_id’den tanıyın. Doğrulayamadığınız istekte HTTP 200 ile {"status":"ERROR","code":"INVALID_SIGNATURE"} dönün; çıplak 401 belirsiz sayılır ve test paketinin SIG-04 senaryosu geçmez. Gövdede tanımadığınız alanları yok sayın.

API idempotency

Operatör API’sindeki her yazma isteği X-Request-Id taşımalıdır; eksikse veya 128 karakteri aşarsa 422 VALIDATION_ERROR (details.field) döner. Kimlik operatör ve ortam başınadır ve 24 saat saklanır. Bu sayede ağ hatasından sonra güvenle tekrar edebilirsiniz; çift kampanya oluşmaz.

Aynı kimlik, aynı metot, yol, sorgu ve gövde: ilk yanıt aynen döner, X-Idempotent-Replay: true başlığıyla.
Aynı kimlik, farklı istek: 409 REQUEST_ID_CONFLICT.
İlk istek hâlâ işleniyorsa: 409 REQUEST_IN_PROGRESS; biraz sonra aynı istekle tekrar edin.
4xx yanıtlar da saklanır. Örneğin GAME_DISABLED veya SCOPE_MISSING alan istek aynı kimlikle tekrar edilirse aynı hata döner. Sorunu giderdikten sonra yeni bir X-Request-Id kullanın. İstisna: kimlik alınmadan önce dönen INVALID_JSON ve alan doğrulaması (VALIDATION_ERROR + details.fields) saklanmaz.
5xx yanıtlar saklanmaz; aynı kimlikle tekrar edebilirsiniz. İmza, IP ve hız limiti hataları (401, 403 IP_NOT_ALLOWED, 429) kimliği tüketmez.

Kapsamlar

Kapsam	Uç noktalar	Ek koşul
games.read	GET /v1/games, GET /v1/games/{game_id}, GET /v1/providers, GET /v1/limits, GET /v1/limits/rules, GET /v1/availability, GET /v1/jackpots, GET /v1/lobby/categories, GET /v1/lobby/recommendations	Jackpot ucu için jackpot modülü etkin olmalı
game.launch	POST /v1/game/launch
rounds.read	GET /v1/rounds, GET /v1/rounds/{round_id}, GET /v1/transactions, GET /v1/jackpots/{pool_id}/wins, GET /v1/live/stream	Düşüş geçmişi için jackpot, canlı akış için live modülü etkin olmalı
freerounds.write	POST /v1/freerounds, GET ve DELETE /v1/freerounds/{id}, POST ve GET /v1/freerounds/{id}/players, DELETE /v1/freerounds/{id}/players/{player_id}	promo modülü etkin olmalı
reports.read	GET /v1/reports/ggr	api modülü etkin olmalı
limits.write	PUT /v1/limits/rules
availability.write	PUT /v1/availability/rules
lobby.write	PUT /v1/lobby/categories
reconciliation.read	GET /v1/reconciliation/stuck-rounds, GET /v1/reconciliation/daily
reconciliation.write	POST /v1/reconciliation/stuck-rounds/{round_id}/resolve, POST /v1/reconciliation/daily
wallet_health.read	GET /v1/wallet-health
marketing.read	GET /v1/marketing/assets, GET /v1/releases
player_events.write	POST /v1/player-events

Kapsamlar anahtar başına değil operatör başınadır ve bütün anahtarlarınıza uygulanır. Yeni hesapta game.launch, games.read, rounds.read, reports.read ve wallet.seamless (hiçbir uç istemez) açıktır; diğerlerini (örn. freerounds.write, reconciliation.write) Boss Hub açar, hesap yöneticinizden isteyin. Kapsam eksikse 403 SCOPE_MISSING (details.scope), modül kapalıysa 403 MODULE_DISABLED döner. Tüm kodlar: Hata kodları.

Hız limiti

Limit operatör ve ortam başınadır. Size özel bir değer tanımlı değilse dakikada 3.000 istek uygulanır. Aşılırsa 429 RATE_LIMITED döner; Retry-After başlığı ve gövdedeki retry_after kaç saniye beklemeniz gerektiğini söyler. Canlı’da (production) istekler ayrıca IP izin listesinden geçmelidir.

Hata gövdesi

API hataları {code, message, request_id} döner; koda göre details ve retry_after eklenir. message İngilizcedir, Accept-Language: tr gönderirseniz Türkçe gelir; iş mantığını code üzerine kurun. request_id sunucunun verdiği kimliktir ve X-Boss-Request-Id yanıt başlığında da gelir; sizin X-Request-Id değeriniz değildir. Destek talebinde bu değeri paylaşın.

← ÖncekiHızlı başlangıç Sonraki →Ortamlar & IP allowlist