TOTP

TOTP(Time-based one time password) birçok sağlayıcı tarafından desteklenen standart bir algoritmadır. (ayrıntılar)

TOTP Setup

Kullanıcı için TOTP secret ve recovery kodları oluşturur. Google authenticator gibi uygulamalarda kolay ekleme yapılması için QR kod datası aktarılır. Şu an için 5 adet tek kullanımlık recovery kod tanımlanmaktadır.

Hesap için tek TOTP tanımlaması yapılabilir. TOTP tanımlaması yapılmış bir hesap setup isteği yollarsa hata alır.

Authentication

• x-auth + 2FA

HTTP Request

POST /auth/totp/setup

Response Parameters

Field	Type	Nullable	Desc
base32	json	false	OTP secret key
otpAuthUrl	json	false	OTP auth url formatında secret
qrDataUrl	json	false	QR kod verisi <img src="qr_data_url"> şeklinde tarayıcıda görüntüleyebilirsiniz.
recoveryCodes	json	false	OTP recovery kodları her biri tek kullanımlıktır.

Response Body Example

{
  "challenge": {
    "challengeId": "NkBVKUoaYkWRTzze",
    "ts": 1754553529150,
    "status": "PENDING",
    "expire": 600,
    "methodList": [
      {
        "id": "UG6m",
        "name": "MAIL",
        "expire": 120,
        "renewStart": 60,
        "hint": "m***l@gmail.com"
      }
    ]
  }
}

2FA complete response

{
  "action": "TOTP_SETUP",
  "challengeId": "NkBVKUoaYkWRTzze",
  "execResult": {
    "success": true,
    "data": {
      "base32": "PJ4...NZV",
      "otpAuthUrl": "otpauth://totp...DGNZV",
      "qrDataUrl": "data:image/png;base64,iVBORw0...TkSuQmCC",
      "recoveryCodes": [
        "DY3...Goj",
        "yEH...zZt",
        "zB3...Fx8",
        "wYn...Qvo",
        "Uq1...JM7"
      ]
    }
  }
}

---

TOTP Deactivate

Hesabın TOTP kaydını inaktif duruma getirir. Oluşturulmuş tüm recovery kodları expire edilir. Hesabın TOTP tanımlaması yok ise hata döner.

Authentication

• x-auth + 2FA

HTTP Request

POST /auth/totp/deactivate

Response Example

{
  "challenge": {
    "challengeId": "YFRP7JRa9af6Q4Sk",
    "ts": 1754553529150,
    "status": "PENDING",
    "expire": 600,
    "methodList": [
      {
        "id": "kMb8",
        "name": "TOTP",
        "expire": 600,
        "renewStart": 0
      }
    ]
  }
}

2FA complete response

{
  "action": "TOTP_DEACTIVATE",
  "challengeId": "YFRP7JRa9af6Q4Sk",
  "execResult": {
    "success": true
  }
}

---

TOTP Recovery

Recovery kodu ile otp secret'larına tekrar erişim sağlar. Kodlar tek kullanımlıktır. Bu kodlar yalnızca kurulum sırasında ortaya çıkar ve database'de yalnızca hash'leri saklanır. İstek sonrasında kullanıcının bu kodları güvenle kopyaladığından emin olunmalıdır.

Authentication

• x-auth

HTTP Request

POST /auth/totp/recover

Request Parameters

Field	Type	Required	Default	Desc
recoveryCode	string	true	-	OTP recovery code

Request Example

{
  "recovery_code": "5IfcWopVQ266"
}

Response Parameters

Field	Type	Nullable	Desc
base32	json	false	OTP secret key
otpAuthUrl	json	false	OTP auth url formatında secret
qrDataUrl	json	false	QR kod verisi <img src="qr_data_url"> şeklinde tarayıcıda görüntüleyebilirsiniz.

Response Body Example

{
  "base32": "PJ4...NZV",
  "otpAuthUrl": "otpauth://totp...DGNZV",
  "qrDataUrl": "data:image/png;base64,iVBORw0...TkSuQmCC"
}