Temel Kavramlar
Kimlik Doğrulama
API, JWT bearer token ile çalışır. Önce login ile
token alınır, sonra korumalı her istekte bu token bir başlıkta gönderilir.
Akış
Login isteği
POST /api/auth/login — Anonim
LoginRequest{
"loginIdentifier": "test_kullanici",
"password": "sifre123"
}
Token ve kullanıcı bilgisi döner
LoginResponse (data){
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
"expiresOnUtc": "2026-07-25T18:30:00Z",
"user": { "...": "AuthenticatedUserResponse" }
}
Token'ı sonraki isteklerde gönder
Authorization: Bearer <accessToken>
Request alanları — LoginRequest
| Alan | Tip | Açıklama |
|---|---|---|
loginIdentifier | string | Kısa kullanıcı adı veya e-posta. |
password | string | Kullanıcı şifresi. |
Cevap alanları — LoginResponse
| Alan | Tip | Açıklama |
|---|---|---|
accessToken | string | JWT bearer token. Korumalı isteklerde Authorization başlığında gönderilir. |
expiresOnUtc | string (UTC datetime) | Token'ın geçerlilik bitiş anı (UTC). Bu andan sonra yeniden login gerekir. |
user | AuthenticatedUserResponse | Giriş yapan kullanıcının özet bilgisi (aşağıda). |
AuthenticatedUserResponse
| Alan | Tip | Açıklama |
|---|---|---|
id | int | Kullanıcının ID'si. |
uniqueIdentifier | guid | Kullanıcının benzersiz ID'si. |
email | string | E-posta adresi. |
username | string | Kısa kullanıcı adı. |
nameSurname | string | Ad soyad. |
grade | int | Sınıf düzeyi. |
studyRoomId | int | Bağlı olduğu çalışma odası (study room) ID'si. |
currentWpm | int | Güncel okuma hızı (kelime/dakika). |
isPasswordSet | bool | Kullanıcının şifresi ayarlanmış mı. |
Hangi endpoint token ister?
| Erişim | Endpointler |
|---|---|
| Anonim | POST /api/auth/login, GET /api/health |
| Bearer | Diğer tüm public endpointler (me, paragraphs, assignments, game-sessions). |
ApiResponse zarfında gelmez — doğrudan 401 statüsüdür.
Çözüm: yeniden login olup yeni token al.
Yeni kullanıcı kaydı (register)
Yeni bir bireysel öğrenci hesabı iki adımda oluşturulur. Tüm bu endpointler
Anonim'dir ve access token döndürmez;
kayıt tamamlandıktan sonra normal login çağrılır.
Kaydı başlat
POST /api/auth/register
İstek gövdesi{
"email": "ogrenci@ornek.com",
"username": "ogrenci1",
"password": "sifre123",
"grade": 5,
"nameSurname": "Ad Soyad", // opsiyonel
"language": "tr" // opsiyonel
}
E-posta doğrulama açıksa: yanıtta registrationIdentifier döner
ve e-postaya bir OTP gönderilir (2. adıma geç). Kapalıysa:
isRegistrationCompleted: true döner ve kullanıcı oluşmuştur
(doğrudan login'e geçebilirsin).
OTP ile tamamla
POST /api/auth/register/confirm
{
"registrationIdentifier": "<register'dan dönen GUID>",
"otp": "<e-postaya gelen kod>"
}
Başarılıysa kullanıcı oluşur; ardından login ile token al.
Şifre sıfırlama
İki adım, her ikisi de Anonim:
- POST /api/auth/password-reset/request —
gövde
{ "loginIdentifier": "e-posta veya kullanıcı adı" }. E-postaya 8 haneli OTP gönderir. Güvenlik için kullanıcının var olup olmadığını sızdırmaz (her durumda kabul yanıtı döner). - POST /api/auth/password-reset/confirm —
gövde
{ "otp": "...", "newPassword": "..." }. Şifreyi günceller; sonra yeni şifreylelogin.
E-posta doğrulama
İki adım, her ikisi de Anonim:
- POST /api/auth/email-verification/request —
gövde
{ "loginIdentifier": "..." }. E-postaya tek kullanımlık token gönderir. - POST /api/auth/email-verification/confirm —
gövde
{ "token": "..." }. E-postayı doğrulanmış olarak işaretler.
login olabilir. Ayrıca
OTP/token yalnızca dev/test konfigürasyonunda yanıt gövdesinde
döner (oneTimeOtp/oneTimeToken); production'da yalnızca
e-postaya gider.
Unity örneği
UnityWebRequest ile korumalı çağrıvar req = UnityWebRequest.Get("https://api.readhaven.co/api/me/profile");
req.SetRequestHeader("Authorization", "Bearer " + accessToken);
yield return req.SendWebRequest();
// req.downloadHandler.text -> ApiResponse<MeProfileResponse> JSON
expiresOnUtc'yi istemcide takip et; geçmeden ya da 401 alınca
yeniden login ol. (Şu an ayrı bir refresh-token endpoint'i yoktur.)