Sorun giderme

Push bildirimi gelmedi

Bunları sırayla deneyin. Çoğu zaman ilki yeter.

1. Touchque Authenticator’ı açın. Uygulama bağlandığında hâlâ bekleyen ve süresi dolmamış her isteği yeniden alır. Bildirim gelmese de istek uygulamada görünür. İstek 30 saniye yaşar; geçtiyse yeni bir istek gönderin.
2. Bildirim izni. Telefonun ayarlarında Touchque Authenticator için bildirimler açık olmalı; Odak / Rahatsız Etmeyin modu bildirimleri gizleyebilir.
3. İnternet. Push için telefonun internete bağlı olması gerekir. İnternet yoksa çevrimdışı onayı kullanın: Çevrimdışı onay.
4. İstek gerçekten gönderildi mi? login.request yanıtına bakın. 404: kullanıcının bağlı telefonu yok, push gitmedi. 403 blocked: risk motoru reddetti (vaka koduna bakın). 429 rate_limited: bu kullanıcıya 10 dakikada 5 push sınırı doldu. 423 frozen: çok sayıda ret yüzünden 2FA donduruldu. Panelde Logs sayfası her isteği ve sonucunu gösterir.
5. Doğru telefon mu? Push, kullanıcının bağladığı telefona gider. Uygulama yeniden kurulduysa ya da telefon yedekten geri yüklendiyse anahtarlar kaybolur (403 device_keys_lost): kullanıcı telefonu yeniden bağlar.

Vaka kodları (K7P-2QX): ne oldukları ve nasıl bakılır

Her login.request yanıtı ve her ret (403 blocked, 403 device_keys_lost, 423 frozen, 429 rate_limited) bir caseCode taşır: K7P-2QX gibi 6 karakter. Touchque'nun o istek için verdiği kararın adıdır. SDK'lar kodu hataya da koyar (err.caseCode).

1. Ret ekranınızda kodu gösterin: "Destek ekibinize söyleyin: K7P-2QX".
2. Ekibiniz Touchque panelinde Logs sayfasını açar ve üstteki Look up a case alanına kodu yazar.
3. Karar penceresi açılır: nedenler, yapılan her kontrol, eşleşen kural ve isteği neyin geçireceği.

Sayı eşleştirme ve passkey yanıtları, kullanıcıya olduğu gibi gösterebileceğiniz sade nedenler de ([{ code, text }]) taşır.

Yeni telefon ya da kayıp telefon

Kullanıcının yeni telefonu var ve eskisi hâlâ elinde

Sizin tarafınızda yapılacak bir şey yok. Kullanıcı eski telefonda Touchque Authenticator'ı açar ve aktarmayı başlatır ("Hesaplarınızı yeni telefona aktarın"), transfer QR'ını yeni telefonla okutur ve yeni telefonda görünen sayıyı yazar. Seçilen hesaplar eski telefonun imzasıyla taşınır ve eski telefondan silinir. Sonraki push yeni telefona gider.

Telefon kayıp, bozuk ya da çalındı

Bunları en güvenliden başlayarak sırayla sunun:

1. Kurtarma kodu. Kayıtta gösterdiğiniz 10 koddan biri bekleyen bir giriş isteğini onaylar. Kritik işlemler ve passkey ya da telefon isteyen girişler kurtarma koduyla onaylanamaz. Girişten sonra kullanıcı yeni telefonunu bağlar.
2. Passkey. Kullanıcı sitenizde passkey kaydettiyse onunla girebilir: Passkey.
3. İş arkadaşlarının onayıyla yeni telefona taşıma (Never Locked Out). Şifre adımından sonra recovery.start bir QR verir; yeni telefon onu okutur. Kullanıcının seçtiği en az iki iş arkadaşı kendi telefonlarında onaylar, bir bekleme süresi geçer (eski telefon ve onaylayanlar bu sürede durdurabilir) ve hesap yeni telefona geçer. Sonraki 24 saat kritik işlemler kapalı kalır.
4. Sizin yaptığınız sıfırlama. Son çare. Kullanıcının kim olduğunu kendi yönteminizle güçlü biçimde doğrulayın (dolandırıcılar tam olarak bu adımı hedefler), sonra secret’ı sıfırlayın: eski telefon onay veremez olur, yeni bir QR ve yeni kurtarma kodları gelir, donmuş 2FA da açılır.

// Kullanıcı "Telefonuma ulaşamıyorum"a basıp kurtarma kodunu yazdı;
// pending.requestId 3. adımda gönderdiğiniz giriş isteğidir.
await tq.login.approveWithRecoveryCode({ requestId: pending.requestId, code: typedCode });

tq.login.approve_with_recovery_code(pending['request_id'], typed_code)

$tq->login->approveWithRecoveryCode($pending['request_id'], $typedCode);

_, err := tq.Login.ApproveWithRecoveryCode(pending.RequestID, typedCode)

await tq.Login.ApproveWithRecoveryCodeAsync(pendingRequestId, typedCode);

tq.login.approve_with_recovery_code(session[:pending_2fa]["request_id"], typed_code)

tq.login().approveWithRecoveryCode(pendingRequestId, typedCode);

// Şifre adımı geçtikten sonra, kullanıcı "Yeni telefonuma taşı" dedi:
const r = await tq.recovery.start({ externalUsername: user.email, clientIp: req.ip, displayName: user.name });
showQr(r.bindUri); // yeni telefondaki Touchque Authenticator bunu okutur

// Kullanıcı beklerken:
const now = await tq.recovery.status(r.recoveryId);
// AWAITING_DEVICE → VOUCHING → COOLING → COMPLETED (ya da VETOED, EXPIRED, FAILED)

// Yalnız kullanıcının kim olduğunu kendi yönteminizle doğruladıktan sonra:
const { qrCodeDataUrl, recoveryCodes, expiresAt } = await tq.auth.resetSecret({ externalUsername: user.email });
// Eski telefon artık onay veremez. Yeni QR'ı ve yeni kurtarma kodlarını gösterin.

reset = tq.auth.reset_secret(user.email)  # reset['qrCodeDataUrl'], reset['recoveryCodes']

$reset = $tq->auth->resetSecret($user->email); // $reset['qrCodeDataUrl'], $reset['recoveryCodes']

reset, err := tq.Auth.ResetSecret(user.Email) // reset.QRCodeDataURL, reset.RecoveryCodes

var reset = await tq.Auth.ResetSecretAsync(user.Email); // reset.QrCodeDataUrl, reset.RecoveryCodes

reset = tq.auth.reset_secret(user.email) # reset["qrCodeDataUrl"], reset["recoveryCodes"]

JsonNode reset = tq.auth().resetSecret(user.getEmail()); // reset.path("qrCodeDataUrl"), reset.path("recoveryCodes")

QR kodu telefonu bağlamıyor

• Secret 5 dakika geçerlidir. Süresi dolan QR çalışmaz (410): yeni bir secret oluşturun.
• Bir secret bir kez kullanılır (409). Telefon zaten bağlıysa yeni secret yerine önce sıfırlayın.
• QR'ı Touchque Authenticator içinden okutun; telefonun kamera uygulamasıyla değil.
• Bağlantıyı getUser ile kontrol edin: bağlıysa used: true ve bir deviceId vardır.

Webhook gelmiyor ya da imzası tutmuyor

• Callback URL panelde Developers → Webhooks altında girilmiş olmalı ve HTTPS olmalı (yerel testte localhost olabilir).
• 5 saniye içinde 2xx dönün; dönmezseniz Touchque birkaç kez yeniden dener. Ağır işi yanıttan sonra yapın.
• İmzayı ham gövde üzerinde doğrulayın: gövdeyi JSON olarak çözüp yeniden yazmayın. Express’te bu yol için express.raw kullanın.
• İmza, bu entegrasyonun API secret’ıyla atılır; Developers → Webhooks sayfasındaki Signing secret aynı değerdir. Anahtarı yenilediyseniz sunucunuzdaki secret’ı da güncelleyin.
• Aynı olay iki kez gelebilir: jti ya da requestId ile tekrarları ayıklayın. Webhook hiç gelmiyorsa durum sorgusuyla (login.status) devam edebilirsiniz.

API çağrıları 401 ya da 403 dönüyor

• 401: bir şey eksik ya da eski; yanıt gövdesindeki error hangisi olduğunu söyler. x-api-key header'ı yok, ya da SIGNATURE_REQUIRED, TIMESTAMP_REQUIRED, TIMESTAMP_EXPIRED (x-timestamp sunucu saatinden 5 dakikadan fazla sapmış: saati NTP ile eşitleyin), NONCE_REQUIRED, NONCE_INVALID (nonce tekrar kullanılmış ya da 16 karakterden kısa). 401 hiçbir zaman yanlış imza anlamına gelmez.
• 403 SIGNATURE_INVALID: imza tutmadı. Doğru secret'ı kullanın (anahtarı yenilediyseniz yenisini); imzalanan yol, sorgu dizesiyle birlikte tam olarak çağırdığınız yoldur; gövde gönderdiğiniz bayt dizisinin aynısıdır; GET istekleri boş gövdeyle imzalanır. SDK'lar bunları sizin yerinize yapar. Bkz. Kimlik doğrulama.
• 403 anahtar için: Invalid API key (böyle bir anahtar yok), Credential has been revoked, credential_expired (panelde yenileyin), credential_org_access_revoked (anahtarı oluşturan kişi artık organizasyonda değil), insufficient_scope (anahtarın bu alan için yetkisi yok).
• 403 IP not allowed: IP izin listesi kullanıyorsanız sunucunuzun çıkış adresi listede olmalı. Diğer kodlar: Hata kodları.

Hâlâ çözülmedi mi? Vaka kodu ya da requestId ile support@touchque.com adresine yazın.