2FA

Standartlaştırılmış dinamik 2FA yapısı.

Tanımlar

2FA akışı herhangi bir endpoint önüne eklenerek isteğin gerekli kimlik doğrulama araçlarından alınan onaylar sonrasında asenkron gerçekleşmesine olanak sağlar. Fakat kimlik doğrulama araçları, kullanıcı hesabına ve sahip olduğu kimlik doğrulama araçlarının durumuna bağlı olarak değişkenlik gösterebilir. Bu sebepten ötürü, hangi kimlik doğrulama araçlarının kullanılacağına istek anında API'de karar verilir ve client uygulamaya aktarılır, client uygulama bu bilgi ile akışı yönetir.

2FA süreci başlatan bir endpoint response olarak challenge ve result şeklinde iki alan döner. result objesi yalnızca gerçekleştirilmek istenen aksiyon doğrudan gerçekleşirse döner ve aksiyona göre farklılık gösterir. Fakat challenge objeleri standarttır.

Challenge

Challenge objesi aşağıdaki alanlara sahiptir.

Field	Type	Required	Desc
`challengeId`	`string`	`true`	2FA challenge id
`ts`	`number`	`true`	Challenge create epoch ts
`status`	`string`	`true`	`PENDING`, `COMPLETED`
`expire`	`number`	`true`	Challenge expire süresi(saniye)
`methodList`	`method[]`	`true`	Method listesi

Method

4 tip method ismi tanımlanmıştır.

Type	Desc
`TOTP`	Google auth gibi uygulamalar aracılığıyla time-based OTP
`PUSH`	Tanımlı cihaz kaynaklı kriptografik imza ile onay
`MAIL`	Email adresine gönderilen OTP
`SMS`	Telefon numarasına gönderilen OTP

Challenge'ların methodList alanı içinde birden fazla method olabilir, teknik açıdan bir limit yoktur. Method objeleri aşağıdaki gibidir.

Field	Type	Required	Desc
`id`	`string`	`true`	Method id
`name`	`string`	`true`	Method ismi
`expire`	`number`	`true`	Method expire süresi(saniye)
`renewStart`	`number`	`true`	Method yenileme başlangıç süresi(saniye) (`0`: forbidden)
`hint`	`string`	`false`	OTP gönderilen tel no veya mail adresi, kısmi gizlenmiş

Example

{
  "challengeId": "EHo2BgM8ndGvEQVm",
  "status": "PENDING",
  "expire": 600,
  "methodList": [
    {
      "id": "4E4H",
      "name": "MAIL",
      "expire": 120,
      "renewStart": 60,
      "hint": "m***l@gmail.com"
    }
  ]
}

2FA Method tamamla

2FA süreci için oluşturulan challenge method'larından birini tamamlamak için kullanılır.

Authentication

p-auth
public + device_signature(required)

Push bildirimine onay verilmesi sırasında p-auth kullanıcının aktif cihazında olmayacağından ötürü, bu endpoint yalnızca push method'unda tokensız da çalışmaktadır. Tokensız çalıştığı durumda cihaz imzası zorunludur.

HTTP Request

POST /auth/2fa/challenge/complete

Request Parameters

JSON object.

Field	Type	Required	Default	Desc
`challengeId`	`string`	`false`	-	2FA challenge id, yalnızca push bildirimi yanıtlarken girilmesi yeterlidir.
`methodId`	`string`	`true`	-	2FA method id
`method`	`string`	`true`	-	2FA method
`value`	`string`	`true`	-	2FA secret, PUSH method için `APPROVED`(onaylandı) veya `DENIED`(reddedildi)
`deviceId`	`string`	`false`	-	PUSH onayında cihaz imzası için eklenir.

Request Body Example

{
  "methodId": "WgRy",
  "method": "TOTP",
  "value": "180762"
}

{
  "challengeId": "EHo2BgM8ndGvEQVm",
  "methodId": "WgRy",
  "method": "PUSH",
  "value": "APPROVED",
  "deviceId": "a1b2c3d4"
}

Response Parameters

Field	Type	Required	Default	Desc
`action`	`string`	`true`	-	Gerçekleştirilmek istenen aksiyon kodu
`execResult`	`json`	`false`	-	Tamamlanması gereken son method ise aksiyon sonucu bu alana eklenir

Response Body Example

İki adet method içeren bir aksiyonun tamamlama isteklerinin cevapları.

{
  "action": "RESET_PASSWORD"
}

{
  "action": "RESET_PASSWORD",
  "challengeId": "NkBVKUoaYkWRTzze",
  "execResult": {
    "success": true
  }
}

2FA Method yenile (SMS, MAIL)

SMS ve MAIL tipindeki method'ları yenilenmesini sağlar.

Hangi method'ların yenileme desteği olduğu 2FA akışı başlatan bir isteğin response'undaki methodList alanındaki objelerdeki renewStart alanı ile anlaşılabilir. Yenileme desteği olan method'ların renewStart alanında saniyeyi temsil eden pozitif bir değer bulunur. Bu alanda 0 değeri olması yenilemenin desteklenmediğini belirtir. Bu alan içindeki pozitif değer method oluşturulduktan kaç saniye sonra yenilemenin mümkün olduğu anlamına gelir.

Bir challenge içindeki herhangi bir method yenilenirse method için otp kodu yeniden oluşturulur ve expire süresi tazelenmiş olur. Challenge içindeki tamamlanmamış diğer method'lardan kalan süresi yenilenen method'un expire süresinden kısa ise uzatılır.

Örneğin SMS, MAIL tiplerinde 2 method içeren bir challenge olsun. Method'ların expire süreleri 120 saniyedir.

API SMS otp olarak 112233 ve MAIL otp olarak 998877 üretmiş olsun.
Expire olmalarına 20 saniye kala kullanıcı SMS method'unu yenilesin.
İstek sonrasında API yeni bir SMS otp kodu(446655) oluşturur, SMS expire süresi 120 saniye olur. MAIL otp kodu değişmez ve expire süresi 120 saniye olacak şekilde güncellenir. Ekleme yapılmaz, güncellenir.

Method yenilemelerinde challenge expire süresi üst limittir. Challenge expire olmasına 120 saniyeden az süre kalmış ise SMS veya MAIL yenileme işlemi yapılamaz.

Authentication

p-auth

HTTP Request

POST /auth/2fa/challenge/renew

Request Parameters

JSON object.

Field	Type	Required	Default	Desc
`methodId`	`string`	`true`	-	2FA method id
`method`	`string`	`true`	-	2FA method

Request Body Example

{
  "methodId": "RKsq",
  "method": "SMS"
}

Socket

Web'den başlatılan süreçler için eklenmiştir. Web client, kayıtlı mobil cihazdan onay verildiği bilgisini bu soket ile alabilir. Aynı şekilde aksiyon tamamlandığında sonucu(login durumu için jwt token bilgileri) soket mesajı olarak yayınlanır.

Oluşan p-auth token ile stream /2fa soketine baglanarak challenge'ın durumu hakkında anlık bilgi alınabilir ve challenge tamamlandığında sonucu bu soketten yayınlanır.

Token'ı p-auth header'ına veya aynı isimdeki query string parametresine ekleyerek bağlantı kurulabilir. Token geçerlilik süresi sona erdiğinde bağlantı sunucu tarafından otomatik sonlandırılır.

Authentication

p-auth

Method Complete Message

Data alanındaki hangi method'un tamamlandığı bilgisi yer alır. Aşağıdaki örnekte gD36dW1GUZQNPTVs id'li challenge'ın b1bG id'li PUSH tipi method'unun tamamlandığı bilgisi aktarılmıştır.

{
  "challengeId": "gD36dW1GUZQNPTVs",
  "action": "LOGIN",
  "event": "METHOD_COMPLETE",
  "data": [
    {
      "methodId": "b1bG",
      "method": "PUSH"
    }
  ]
}

Action Complete Message

{
  "challengeId": "MGzAscUPbWhs6aka",
  "action": "LOGIN",
  "event": "ACTION_COMPLETE",
  "data": [
    {
      "success": true,
      "data": {
        "sessionKey": "26075a0f8d0073c526c806ccbc9fe3cbb0bc48fea7f909f2be9e7ad86a75da9d"
      },
      "headers": {
        "x-auth": "eyJhb...aMn_0",
        "ot-auth": "eyJhb...nphnc"
      }
    }
  ]
}

2FA Challenge sonucu

Soket baglantısında sorun olması durumunda web client kullanması için eklenen bir endpointtir. Challenge sonuncda oluşması beklenen veriyi döner.

Authentication

p-auth

HTTP Request

GET /auth/2fa/challenge/result

Response Parameters

execResult objesinin içeriği gerçekleştirilmek istenen aksiyona göre değişiklik gösterir.

Field	Type	Required	Default	Desc
`action`	`string`	`true`	-	Aksiyon ismi (`LOGIN`, `TOTP_SETUP`, `...`)
`challengeId`	`string`	`true`	-	Challenge id
`execResult`	`json`	`true`	-	Gerçekleştirilen aksiyon sonucu

Response body example

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

Aktif push onaylarını getir

Client uygulamaya push izinleri verilmemiş bir cihazda client uygulama push bilgilerini kullanıcı giriş yapmadan önce almak için bu endpoint'i kullanır.

infoTable alanındaki bilgileri kullanarak onay sayfasında verilmesi istenen bilgileri gösterebilirsiniz.

Authentication

public + device_signature(required)

HTTP Request

GET /auth/2fa/challenge/ongoing

Request Parameters

Field	Type	Required	Default	Desc
`deviceId`	`string`	`true`	-	Cihaz id'si

Response Body Example

[
  {
    "body": "Hesabınıza girişi onaylamak için tıklayın.",
    "data": {
      "challengeId": "oKyScYDcGggk9u5m",
      "ts": 1754553529150,
      "methodId": "i6tn",
      "action": "LOGIN",
      "actionTitle": "Account Login",
      "params": {
        "ip": "104.247.174.90",
        "deviceBrand": "MacOS",
        "deviceModel": "Firefox 140",
        "deviceDesc": "MacOS / Firefox 140",
        "dateTime": "07.08.2025 07:58:49 (GMT+3)",
        "timestamp": 1754553529150,
        "countryName": "Turkiye",
        "infoTable": {
          "metadata": {
            "type": "simple",
            "rows": 2,
            "cols": 2
          },
          "data": [
            [
              "IP / Location",
              "104.247.174.90 / Turkiye"
            ],
            [
              "Device Info",
              "MacOS / Firefox 140"
            ]
          ]
        },
        "expire": 114
      }
    }
  }
]

Tanımlar​

Challenge​

Method​

Example​

2FA Method tamamla​

Authentication​

HTTP Request​

Request Parameters​

Request Body Example​

Response Parameters​

Response Body Example​

2FA Method yenile (SMS, MAIL)​

Authentication​

HTTP Request​

Request Parameters​

Request Body Example​

Socket​

Authentication​

Method Complete Message​

Action Complete Message​

2FA Challenge sonucu​

Authentication​

HTTP Request​

Response Parameters​

Response body example​

Aktif push onaylarını getir​

Authentication​

HTTP Request​

Request Parameters​

Response Body Example​

Tanımlar

Challenge

Method

Example

2FA Method tamamla

Authentication

HTTP Request

Request Parameters

Request Body Example

Response Parameters

Response Body Example

2FA Method yenile (SMS, MAIL)

Authentication

HTTP Request

Request Parameters

Request Body Example

Socket

Authentication

Method Complete Message

Action Complete Message

2FA Challenge sonucu

Authentication

HTTP Request

Response Parameters

Response body example

Aktif push onaylarını getir

Authentication

HTTP Request

Request Parameters

Response Body Example