Kimlik doğrulamaya genel bakış

Bu sayfa oyuncunun Open Play’e nasıl giriş yaptığını özetler: hangi yöntemler var, hepsinin paylaştığı kurallar neler ve ayrıntı için hangi sayfaya gidilir. Oyuncu girişini bağlıyorsanız önce buradan başlayın.

Giriş yöntemleri

Hangi yöntemlerin oyuncuya sunulacağı oyunun tercihidir; Google’ın çalışması için ortamda yapılandırılmış olması gerekir (Oyun ayarları › Giriş yöntemleri).

Giriş sonrası konular: Oturumlar ve CSRF, Hesap bağlama, Sunucuda doğrulama.

Hangi yöntemi seçmeliyim?

• Hesap zorunlu değilse misafirle başlayın; oyuncu ilerledikçe misafir terfisi ile e-postaya ya da Google’a bağlayın. Oyuncu kimliği (playerId) değişmez.
• Çoklu cihaz istiyorsanız e-posta/parola ya da Google gerekir; misafir kimliği cihazın sakladığı sırra bağlıdır.
• Mobil yerel giriş (Apple, Game Center, Play Games) için HTTP uçları vardır, ancak SDK’larda yardımcı yoktur.

Her çağrıda geçerli kurallar

Aşağıdaki kurallar /v1/auth/* altındaki tüm uçlar için geçerlidir.

1. Ortam başlığı. Her istek x-crx-env: <ortam-kimliği> taşır. Yoksa ya da UUID değilse 401.

2. İçerik türü. Gövdeli istekler Content-Type: application/json ile gönderilir.

3. CSRF. GET dışındaki her istek, çift gönderim (double-submit) CSRF koruması ister: __Secure-crx.csrf çerezi ve eşleşen x-csrf-token başlığı. Her başarılı kullanımda belirteç döner ve değişir. Önce GET /v1/auth/csrf ile bir belirteç alırsınız. Ayrıntı: Oturumlar ve CSRF.

4. Origin denetimi. Tarayıcıdan gelen durum değiştiren isteklerin Origin alan adı ortama bağlı olmalıdır. Bkz. Mimari ve barındırma.

5. Alan adları snake_case. İstek ve yanıt gövdeleri snake_case kullanır (display_name, bootstrap_token, old_password). İki istisna: GET /v1/auth/session yanıtında displayName ve POST /v1/auth/session/display-name gövdesi/yanıtı (displayName). SDK’lar bu farkı sizden saklar ve camelCase sunar.

6. Hata gövdeleri. Hatalar çoğunlukla düz metindir (permission denied, rate limited…). JSON gövdeli tek anlamlı hata, banlı hesap için 403 {"code":"account_banned","message":"account banned"} yanıtıdır. Durum kodları: 400 geçersiz girdi, 401 ortam ya da oturum yok/geçersiz, 403 reddedildi (yanlış parola, CSRF, süresi dolmuş token — ayrım bilerek sızdırılmaz), 409 çakışma, 422 işlenemez, 429 oran sınırı. Ayrıntı: Hatalar.

Başarılı giriş yanıtı

Giriş, kayıt, yenileme ve OAuth callback uçları aynı zarfı döndürür ve iki çerez yazar (__Secure-crx.session, __Secure-crx.refresh; HttpOnly; Secure; SameSite=Lax; Path=/, Max-Age=15552000 = 180 gün üst sınır):

{
  "player": {
    "id": "0192…",
    "display_name": "Guest",
    "email": null,
    "email_verified": false,
    "is_guest": true,
    "image": null,
    "created_at": "2026-11-03T10:00:00+00:00"
  },
  "tokens": {
    "session_token": "<64 hex>",
    "refresh_token": "<64 hex>",
    "access_token": "<jwt>",
    "expires_in_secs": 900
  },
  "is_new_player": true
}

Uyarı

Tarayıcı oyunlarında oturum ve yenileme belirteçlerini JavaScript’te saklamayın; çerezler HttpOnly’dir ve bunun için vardır. SDK’lar belirteç gövdelerini durumuna, günlüğe ve hatalara koymaz.

Oran sınırları

Kimlik uçları, sabit pencereli oran sınırlarına tabidir. Aşımda 429 ve düz metin rate limited döner; Retry-After başlığı yoktur: pencere süresini kendiniz beklemelisiniz. Başarısız denemeyi hemen yeniden göndermeyin.

Sunucu önünde fazladan bir vekil varsa ve güvenilen vekil adresleri tanıtılmamışsa bütün oyuncular tek IP kovasına düşer. Bkz. Mimari ve barındırma.

Uç nokta özeti

/v1/auth/organization/* uçları (oyuncu organizasyonları) kullanımdan kalkmaktadır: çalışır, ancak her yanıtı Deprecation başlığı taşır ve bu belgede anlatılmaz. /v1/auth/admin/* uçları sunucu anahtarıyla oyuncu yönetimi içindir (liste, ban, yeniden adlandırma, oturum iptali) ve uç nokta başvurusunda listelenir.

Banlı hesaplar

Operatör bir oyuncuyu banladığında oyuncunun tüm oturumları iptal edilir ve açık gerçek zamanlı bağlantısı kapanır. Oyuncu girişte nasıl görünür:

• Parolası doğru banlı e-posta hesabı: 403 ve {"code":"account_banned","message":"account banned"}. Yanlış parola ya da bilinmeyen adres ayrımsız 403 düz metindir; ban durumu sızmaz.
• Banlı misafir: aynı bootstrap sırrıyla ya da banlı oyuncunun eski oturumunu sunarak misafir girişi yapılırsa yine 403 account_banned döner ve yeni oyuncu açılmaz.
• GET /v1/auth/session banlı hesapta 401 döndürür (ban kodu sızmaz); refresh, OAuth callback ve misafir terfisi banlı sahibe ayrımsız reddedilir.
• Yanıtta ban gerekçesi ya da bitişi yoktur.
• SDK davranışı: TypeScript’te oturum durumu banned olur; Unity’de SessionStatus.Banned. İkisi de yeni misafir açmaz ve kayıtlı misafir sırrını silmez (banlı oyuncu yeni misafir açarak kaçamasın). Oyuncuya hesabın askıya alındığını gösterin; yeniden deneme döngüsü kurmayın.