POST /backend/oauth2/token — OAuth2 Code Verify

📋 Genel Bilgi

OAuth2 authorization_code grant akışı ile uzaktan doğrulama yapılır. Client credentials (client_id, client_secret) ile authorization code exchange edilir.

Base URL: {{wentro}}/backend/oauth2/token Method: POST Content-Type: application/json

---

🔐 Headers

Header	Value
Content-Type	application/json

---

📥 Request Body

{
  "grant_type": "authorization_code",
  "code": "{{auth_code}}",
  "client_id": "{{client_id}}",
  "client_secret": "{{client_secret}}",
  "redirect_uri": "https://example.com/callback"
}

Parametreler

Alan	Tip	Zorunlu	Açıklama	Örnek
grant_type	string	✅	Grant türü (sabit: authorization_code)	"authorization_code"
code	string	✅	Authorization code (OAuth2 flow'dan gelen)	"{{auth_code}}"
client_id	string	✅	OAuth client ID	"{{client_id}}"
client_secret	string	✅	OAuth client secret	-
redirect_uri	string	✅	Yönlendirme URI'si (OAuth client'ta kayıtlı olmalı)	"https://example.com/callback"

---

🔄 Akış Diyagramı (OAuth2 Authorization Code Flow — Uzaktan Doğrulama)

Adım Açıklamaları:

Adım	Taraf	İşlem	Açıklama
1	Servis Sağlayıcı → Müşteri	OAuth authorize endpoint'ine redirect eder	Servis sağlayıcı, müşteriyi API'nin OAuth authorize sayfasına yönlendirir. client_id, redirect_uri ve diğer parametreler gönderilir.
2	Müşteri → Passkey Ekranı	Doğrulama ekranı açılır	Müşteri passkey ile doğrulama yapar (biyometrik, PIN vb.).
3	Müşteri → Passkey Ekranı	Onay verir	Müşteri onayladığında doğrulama tamamlanır.
4	Müşteri → API	Authorization code ile redirect edilir	Doğrulama başarılı olduğunda, müşteri redirect_uri'ye bir authorization code (code) parametresiyle yönlendirilir.
5	API → Servis Sağlayıcı	Authorization code döner	Redirect URI'de ?code=AUTH_CODE formatında authorization code bulunur.
6	Servis Sağlayıcı → API	POST /backend/oauth2/token ile code exchange edilir	Servis sağlayıcı, authorization code'u ve client credentials (client_id, client_secret) ile token endpoint'ine istek gönderir.
7	API → Servis Sağlayıcı	Doğrulama sonucu döner	msisdn, verified, context (cihaz/IP bilgisi) gibi bilgiler döner.
8	Servis Sağlayıcı → Müşteri	Callback'e redirect eder	İşlem tamamlandıktan sonra müşteri callback sayfasına yönlendirilir.
9	Callback → Müşteri	Sayfa gösterilir	Son kullanıcı callback/teşekkür sayfasını görür.

Kullanım Senaryoları:

Senaryo	Açıklama
OAuth2 Entegrasyon (Standart Flow)	Servis sağlayıcı, OAuth2 authorization_code flow'u ile müşteriyi doğrular. client_id ve client_secret ile güvenli token exchange yapılır.
Üçüncü Taraf Doğrulama	Başka bir servis/mobil uygulama üzerinden müşteri doğrulaması gerektiğinde kullanılır.
KVKK / EK Onayı (OAuth2)	Müşterinin KVKK veya Ek Onay (SMS, call, email) onayları OAuth2 flow ile alınır.

---

✅ Response — 200 OK

{
  "success": true,
  "context": {
    "requestId": "11c096cc-938c-4c8a-8363-c9055b4a4851",
    "timestamp": "2026-07-13T12:41:59.848Z",
    "ip": "127.0.0.1",
    "deviceContext": {
      "deviceName": "Desktop Computer",
      "deviceVendor": "",
      "deviceModel": "",
      "deviceType": "desktop",
      "osName": "Windows",
      "osVersion": "10",
      "browserName": "Chrome",
      "browserVersion": "150.0.0.0",
      "cpuArchitecture": "amd64"
    },
    "ipContext": {
      "country": null,
      "countryCode": null,
      "city": null,
      "region": null,
      "regionCode": null,
      "latitude": null,
      "longitude": null,
      "timezone": null,
      "postalCode": null,
      "accuracyRadius": null
    }
  },
  "parsedAt": "2026-07-13T12:41:59.849Z",
  "msisdn": "{{customer_msisdn}}",
  "verified": true,
  "verifiedAt": "2026-07-13 15:42:11"
}

Response Alanları

Alan	Tip	Açıklama
success	boolean	Doğrulama sonucu
context.requestId	string	İstek benzersiz ID (UUID)
context.timestamp	string	İşlem zamanı (ISO 8601)
context.ip	string	İstemci IP adresi
context.deviceContext	object	Cihaz detayları
context.ipContext	object	Coğrafi konum bilgisi (null: localhost)
parsedAt	string	İşlem zamanı (ISO 8601)
msisdn	string	Müşteri telefon numarası
verified	boolean	Doğrulama durumu
verifiedAt	string	Doğrulama zamanı (YYYY-MM-DD HH:mm:ss)

---

❌ Error Responses

⚠️ Önemli: Bu endpoint, projenin geri kalanındaki AppError/Response+Success:false formatını kullanmıyor. Bunun yerine OAuth2 spesifikasyonuna uygun standart error/error_description formatını kullanıyor:

{
  "error": "invalid_grant",
  "error_description": "Geçersiz yetkilendirme kodu"
}

error	error_description	Ne Zaman Oluşur
invalid_request	Gerekli parametreler eksik: grant_type, code, client_id, client_secret	grant_type, code, client_id veya client_secret alanlarından biri boş
unsupported_grant_type	Desteklenmeyen grant_type. Sadece 'authorization_code' destekleniyor.	grant_type değeri authorization_code dışında bir şey
invalid_client	Client bulunamadı	Gönderilen client_id'ye karşılık gelen bir OAuth client kaydı yok
invalid_grant	Redirect URI uyuşmuyor	Gönderilen redirect_uri, client'ta kayıtlı redirect_uri ile eşleşmiyor
invalid_client	Geçersiz client_secret	client_secret yanlış
invalid_grant	Geçersiz yetkilendirme kodu	code'a karşılık gelen bir oauth2_logs kaydı bulunamadı
invalid_grant	Yetkilendirme kodu zaten kullanılmış	code daha önce verified durumuna geçmiş (tek kullanımlık)
invalid_grant	Yetkilendirme kodu süresi dolmuş (10 dakika geçerli)	code'un expiredAt zamanı geçmiş
invalid_grant	Yetkilendirme kodu bu client için geçerli değil	code, farklı bir client_id için üretilmiş

---

📝 Notlar

• Fark: Bu endpoint, Dynamic QR ve Landing Page Auth'dan farklı olarak standart OAuth2 authorization_code flow kullanır. Servis sağlayıcı müşteriyi önce authorize sayfasına redirect eder → müşteri passkey ile doğrular → API'ye code parametresiyle redirect edilir → servis sağlayıcı bu code'u token exchange için kullanır.
• client_secret gizli tutulmalıdır (backend tarafında saklanır, asla client-side'a gönderilmez).
• redirect_uri, OAuth client'ta önceden kayıtlı olmalıdır. Redirect URI eşleşmezse hata döner.
• verifiedAt formatı: YYYY-MM-DD HH:mm:ss.
• Bu endpoint servis sağlayıcı (backend) tarafından çağrılır, müşteri tarafı değil.