Portal — Kimlik & Oturum

Bu uçları kim çağırır?Portal / SDK

Taban yol: /api/portal/v1/wallet/auth
Kimlik: register, login, otp/verify, otp/resend, password/reset* uçları publishable key ile açılır (IP başına hız sınırı vardır). Bu noktadan sonra session, sessions, devices, logout uçları müşteri oturumu ister.
Yetki: Oturumun kendisi yetkidir; kullanıcı yalnız kendi kaydına erişir.Step-up: para çıkaran işlemlerde oturum tek başına yetmez; OTP kodu ya da güvenilir aksiyon token'ı istenir.
Çapraz yüzey: Bu yüzey son kullanıcı içindir; merchant sunucunuz bu uçları çağırmaz. Sunucu tarafı için s2s API'ye bakın.

Son kullanıcı oturumu üç aşamada kurulur: tanıtım (publishable key) → kimlik (kayıt/giriş) → doğrulama (OTP). Hassas işlemlerde bunun üstüne step-up biner.

Tüm uçlar /api/portal/v1/wallet/auth/* altındadır.

Kayıt

POST /api/portal/v1/wallet/auth/register

Alan	Tip	Zorunlu	Açıklama
`phone`	string	✅	Telefon numarası — cüzdanın tekilleştirme anahtarı
`password`	string	✅
`email`	string	—
`programId`	string	—	Birden fazla programınız varsa
`consentCodes`	string[]	—	Kullanıcının onayladığı sözleşme kodları
`device`	object	—	Cihaz tanımı (aşağıda)
`threatPayload`	object	—	Cihaz risk sinyalleri

Cihaz nesnesi:

Alan	Açıklama
`fingerprintHash`	Cihaz parmak izi
`platform`	İşletim sistemi/platform
`installId`	Kurulum kimliği
`deviceName`	Kullanıcıya gösterilecek ad

⚠️

Telefon numarası cüzdanın kimliğidir. Doğrulanmamış bir numarayla cüzdan bağlamak, numarayı ele geçiren birine cüzdanı devretmek demektir — bu yüzden kayıt akışı OTP doğrulaması olmadan tamamlanmaz.

Giriş

POST /api/portal/v1/wallet/auth/login

phone + password (+ opsiyonel programId, device, threatPayload). Yanıt bir OTP doğrulama adımı başlatır ve challengeId döner.

OTP doğrulama

POST /api/portal/v1/wallet/auth/otp/verify     # { challengeId, code, programId?, device? }
POST /api/portal/v1/wallet/auth/otp/resend     # { challengeId, programId? }

Doğrulama başarılıysa oturum açılır: access + refresh token.

otp/resend'i kullanıcıya bir sayaçla sunun. Kod gelmediğinde tekrar göndermek yerine girişi baştan başlatan uygulamalar, kullanıcıyı gereksiz yere döngüye sokar.

Oturum yönetimi

POST /api/portal/v1/wallet/auth/refresh            # { refreshToken? }
POST /api/portal/v1/wallet/auth/logout
GET  /api/portal/v1/wallet/auth/session            # mevcut oturum bilgisi
GET  /api/portal/v1/wallet/auth/sessions           # tüm aktif oturumlar
DELETE /api/portal/v1/wallet/auth/sessions/{sessionId}

GET /api/portal/v1/wallet/auth/sessions ve DELETE /api/portal/v1/wallet/auth/sessions/{id}, kullanıcının "diğer cihazlardaki oturumları kapat" ekranını besler. Bunu ayarlar içine gömün — cüzdan uygulamalarında beklenen bir yetenektir.

Cihaz yönetimi

GET    /api/portal/v1/wallet/auth/devices
PATCH  /api/portal/v1/wallet/auth/devices/{deviceId}    # { deviceName }
DELETE /api/portal/v1/wallet/auth/devices/{deviceId}

Kullanıcı cihazını adlandırabilir ve kaldırabilir. Kaldırılan cihazın oturumu sonlanır.

Şifre işlemleri

POST /api/portal/v1/wallet/auth/password/change            # { currentPassword, newPassword }
POST /api/portal/v1/wallet/auth/password/reset             # { phone, programId? } → challengeId
POST /api/portal/v1/wallet/auth/password/reset/complete    # { challengeId, code, newPassword, programId? }

Şifre sıfırlama da OTP ile doğrulanır.

Step-up doğrulama

Oturum açık olmak, para çıkarmak için yeterli değildir. Transfer, çekim, QR ödeme, fatura ödeme gibi işlemlerde ek doğrulama istenir:

Yöntem	Ne zaman
`otpCode`	İşlem başlatıldığında gönderilen kod
`trustedActionToken`	Daha önce alınmış güvenilir aksiyon token'ı

⚠️

Step-up token'ı tek kullanımlıktır. Aynı token'ı ikinci bir işlemde kullanmayın; her para hareketi kendi doğrulamasını ister.

Rate limit

Kimlik uçları hız sınırlıdır — kaba kuvvet denemeleri ve OTP bombardımanı engellenir. Uygulamanızda:

Ardışık başarısız denemelerde kullanıcıya bekleme süresi gösterin.
OTP tekrar gönderme düğmesini sayaçla kilitleyin.
Otomatik yeniden deneme döngüsü kurmayın.

Akış özeti

Uygulamayı tanıtın

Publishable key ile istek atın.

Kullanıcıyı kaydedin veya giriş yaptırın

register / login → challengeId.

OTP doğrulayın

otp/verify → oturum token'ları.

`/me/*` uçlarını çağırın

Access token ile; yalnız kullanıcının kendi verisi.

Para çıkışında step-up isteyin

otpCode veya trustedActionToken.

Yaygın hatalar

Durum	Sebep	Çözüm
Kayıt tamamlanmıyor	OTP doğrulanmadı	Akışı `otp/verify` ile bitirin
Oturum beklenenden erken düşüyor	Refresh akışı kurulmamış	`auth/refresh` kullanın
Para işlemi 4xx dönüyor	Step-up eksik	`otpCode` / `trustedActionToken` gönderin
Rate limit'e takılıyorsunuz	Otomatik yeniden deneme	Döngüyü kaldırın, kullanıcıya sayaç gösterin

Genel Bakış Hesap & İşlemler