Authentication Flow

Bu sayfa mobile ve web client'ların Allmine API'ye güvenli şekilde giriş yapması, token saklaması ve token yenilemesi için izlenecek sırayı anlatır. Endpoint detayları için API Reference kullanılmalıdır.

Temel kurallar

• Protected endpoint'lerde Authorization: Bearer <accessToken> header'ı zorunludur.
• Telefon OTP ve email OTP akışları public endpoint'lerdir.
• accessToken kısa ömürlüdür; API çağrılarında kullanılır.
• refreshToken sadece token yenilemek ve logout/revoke akışları için saklanmalıdır.
• Mobile client'lar token ile birlikte x-device-id, x-platform, x-app-version, x-timezone ve x-language header'larını göndermelidir.

Authorization: Bearer <accessToken>
x-device-id: iphone-15-pro-max
x-platform: ios
x-app-version: 1.4.2
x-timezone: Europe/Istanbul
x-language: tr

Login sırası

1. Kullanıcı telefon veya email girer.
2. Client OTP gönderim endpoint'lerinden birini çağırır:
   • POST /api/v1/auth/send-otp
   • POST /api/v1/auth/send-otp-email
3. Kullanıcı kodu girdikten sonra verify endpoint'lerinden biri çağrılır:
   • POST /api/v1/auth/verify-otp
   • POST /api/v1/auth/verify-otp-email
4. Response içindeki data.accessToken, data.refreshToken, data.expiresIn, data.refreshExpiresIn, data.user ve data.isRegistrationComplete alanları saklanır.
5. isRegistrationComplete=false ise client onboarding/registration ekranına yönlendirir. Protected API çağrılarında yine access token kullanılabilir, fakat bazı endpoint'ler kayıt tamamlanmadan izin vermeyebilir.

{
  "isSuccess": true,
  "statusCode": 200,
  "data": {
    "accessToken": "<access_token>",
    "refreshToken": "<refresh_token>",
    "expiresIn": 3600,
    "refreshExpiresIn": 2592000,
    "isRegistrationComplete": true,
    "user": {
      "_id": "65f000000000000000000001"
    }
  },
  "errors": [],
  "timestamp": "2026-05-21T10:00:00.000Z"
}

Token yenileme

Client access token süresi dolmadan kısa süre önce veya ilk 401 cevabında tek seferlik refresh denemesi yapmalıdır.

POST /api/v1/auth/refresh
Content-Type: application/json

{
  "refreshToken": "<refreshToken>"
}

Başarılı refresh response'u yeni accessToken ve yeni refreshToken döndürür. Client iki token'ı birlikte değiştirmelidir. Eski refresh token ile paralel istekler yarış durumuna girebileceği için refresh işlemini tek uçtan yönetmek gerekir.

Client davranışı

async function requestWithAuth(input: RequestInfo, init: RequestInit = {}) {
  const response = await fetch(input, {
    ...init,
    headers: {
      ...init.headers,
      Authorization: `Bearer ${auth.accessToken}`,
      "x-device-id": device.id,
      "x-platform": device.platform,
      "x-timezone": Intl.DateTimeFormat().resolvedOptions().timeZone,
    },
  });

  if (response.status !== 401) {
    return response;
  }

  await auth.refreshOnce();

  return fetch(input, {
    ...init,
    headers: {
      ...init.headers,
      Authorization: `Bearer ${auth.accessToken}`,
    },
  });
}

Oturum kapatma

• Kullanıcı çıkış yaptığında POST /api/v1/auth/logout çağrılır ve local token store temizlenir.
• Sadece belirli refresh token iptal edilecekse POST /api/v1/auth/revoke-token kullanılır.
• Aktif oturumları göstermek için GET /api/v1/auth/sessions kullanılabilir.
• Access token geçerli mi kontrolü için GET /api/v1/auth/validate-token çağrılabilir, ancak normal client akışında her ekranda validate çağrısı yapmak yerine API cevaplarına güvenmek daha verimlidir.

Saklama önerisi

Mobile'da token'lar Keychain/Keystore gibi secure storage içinde saklanmalıdır. Web'de refresh token'ın JavaScript erişimine açık uzun süreli storage'da tutulması risklidir; web client için session kapsamı ve backend-for-frontend stratejisi ayrıca değerlendirilmelidir.