Kimlik doğrulama

FlowDesk’te iki ayrı kimlik doğrulama yüzeyi vardır ve bu ayrım kazayla değil, kasıtlı olarak kesindir:

Credential	Nasıl alınır	Nerede geçerli
Panel (dashboard) JWT’si	POST /v1/dashboard/auth/login (veya LDAP/Keycloak/OTP varyantları)	Yalnızca v1/dashboard/*
API token (fd_ önekli)	Panelde bir yönetici tarafından POST /v1/dashboard/api-tokens ile	Yalnızca v1/integration/*

Hızlı başlangıç sayfası bu iki adımı uçtan uca gösterir: panele giriş, token oluşturma, ilk talebi açma. Bu sayfa o akışın neden böyle çalıştığını, oturum davranışını ve bir 401 aldığınızda ne yapacağınızı anlatır.

v1/external/* endpoint’leri (talep takibi, gömülü formlar) bu ikisinden ayrı, kimlik doğrulama gerektirmeyen üçüncü bir yüzeydir; bkz. Talep takibi.

Panel JWT’si

v1/dashboard/auth/login (ve diğer login varyantları) bir RS256 ile imzalı JWT çifti döner:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiIs...",
    "accessTokenExpiresAt": "2026-08-13T10:15:00Z",
    "refreshToken": "8f2c1a...",
    "refreshTokenExpiresAt": "2026-08-20T10:00:00Z"
  }
}

• accessToken: varsayılan 60 dakika geçerlidir (JWT:AccessTokenExpireMinutes). sub (kullanıcı id’si) ve jti (bu token’a özel bir kimlik) taşır; imza doğrulaması özel anahtarla eşleşen genel anahtarla yapılır.
• refreshToken: opak, rastgele üretilmiş bir dize; 7 gün geçerlidir. Sunucu tarafında saklanır (JWT değildir), bu yüzden tek başına anlamlı bir veri taşımaz.

Yenileme ve rotasyon

curl -s -X POST https://api.ornek.com/v1/dashboard/auth/refresh-token \
  -H "Content-Type: application/json" \
  -d '{ "refreshToken": "8f2c1a..." }'

Başarılı bir yanıt, giriş yanıtıyla aynı şekli taşır: yeni bir accessToken ve yeni bir refreshToken. Kullandığınız refreshToken bu çağrıyla birlikte anında geçersiz kılınır. Yeni çift verilmeden önce eskisi silinir. Yani her refresh token tam olarak bir kez kullanılabilir; aynı değeri ikinci kez göndermek başarısız olur (400).

Tek aktif oturum

Bir kullanıcı için yeni bir refresh token verildiğinde (yeni bir login veya bir refresh çağrısı ile), o kullanıcının önceki refresh token’ı hemen geçersiz kılınır. Bu, kullanıcı + platform başına tek aktif oturum demektir: aynı hesapla ikinci bir yerden giriş yaptığınızda, ilk oturumun refresh token’ı sessizce ölür.

Bunun pratik sonucu: ilk oturumun access token’ı kendi 60 dakikalık süresi dolana kadar çalışmaya devam eder (JWT doğrulaması sunucu tarafında bir oturum tablosuna bakmaz). Farkı ilk hissettiğiniz an, ilk oturumun access token’ı süresi dolup da onu yenilemeye çalıştığınız andır: o noktada refresh token zaten geçersizdir ve yeniden giriş yapmanız gerekir.

Çıkış (logout)

curl -s -X POST https://api.ornek.com/v1/dashboard/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Çıkış iki şeyi birden yapar: o access token’ın jti’si, kalan ömrü kadar bir kara listeye alınır (bu yüzden süresi zaten dolmuş bir token’ı loglamanın maliyeti yoktur), ve o kullanıcı+platform için aktif refresh token iptal edilir. Kara listedeki bir jti ile gelen her istek, imzası geçerli olsa bile reddedilir: çıkış yapılmış bir access token’ı tekrar kullanılamaz hâle getiren asıl mekanizma budur.

API token

Entegrasyon endpoint’leri (v1/integration/*) panel JWT’sini hiç tanımaz. Bunun yerine, panelde bir yönetici tarafından oluşturulan, fd_ önekli bir API token ile çalışır: oluşturma akışı ve kapsam (pool) kuralları için Hızlı başlangıç → 2. adım ve Talep açma sayfalarına bakın.

Kısaca: token’ın taşıdığı scopes (tickets:read, tickets:write) hangi endpoint’leri çağırabileceğinizi, poolIds/allPools hangi havuzlarda talep açıp okuyabileceğinizi belirler. Token isteğe bağlı bir expiresAt taşıyabilir; süresi dolan token 401 döner.

Neden panel JWT’si entegrasyon endpoint’lerinde 401 döner

Bu, bu sayfanın en önemli noktası ve gerçek bir kodda uygulanan davranıştır, sözleşme değil:

v1/integration/* altındaki her endpoint, yetkilendirmesini açıkça ApiToken şemasına bağlar ([Authorize(AuthenticationSchemes = "ApiToken", Policy = ...)]). API token’ları doğrulayan handler, Authorization başlığındaki değeri yalnızca fd_ ile başlıyorsa kendi tokenı olarak kabul eder; başlamıyorsa (ör. bir panel JWT’si geldiğinde) o isteğe hiç karışmaz: “bu benim işim değil” der ve sonucu boş bırakır.

Sorun şu: bu endpoint’lerin yetkilendirme politikası yalnızca ApiToken şemasını dinliyor. Panel JWT’sini doğrulayan ayrı şema hiç devreye girmiyor, çünkü bu politika onu hiç çağırmıyor. Sonuç: geçerli, süresi dolmamış bir panel JWT’si gönderseniz bile, v1/integration/* onu hiç görmüş gibi davranmaz: istek kimliği doğrulanmamış sayılır ve 401 döner. Tersi de aynı şekilde işler: bir API token’ı v1/dashboard/* endpoint’lerine göndermek de doğrulanmaz.

İstek	v1/dashboard/*	v1/integration/*
Panel JWT’si (Bearer eyJ...)	Çalışır	401
API token (Bearer fd_...)	401	Çalışır (scope yeterliyse)

401 aldığınızda kontrol listesi

1. Doğru credential’ı mı gönderiyorsunuz? v1/integration/*’a panel JWT’si, v1/dashboard/*’a API token göndermek, yukarıdaki tablodaki gibi, ikisi de 401’dir. Authorization başlığınızın fd_ ile başlayıp başlamadığını kontrol edin.
2. Token süresi dolmuş mu? Panel JWT’si 60 dakikada, refresh token 7 günde; API token’lar isteğe bağlı bir expiresAt ile süresi dolabilir.
3. Token iptal edildi mi? API token doğrulaması 30 saniyeye kadar cache’lenir: panelden yeni iptal edilmiş bir token, bu pencere boyunca hâlâ çalışıyor gibi görünebilir; bu beklenen bir davranıştır, hata değildir.
4. 401 mi, 403 mü aldınız? İkisi farklı şeyler söyler: 401 credential’ınızın geçersiz olduğunu (eksik, bozuk, süresi dolmuş, iptal edilmiş), 403 credential’ınızın geçerli ama bu işlem için yetersiz kapsamlı olduğunu (ör. yalnızca tickets:read olan bir token ile talep açmaya çalışmak) söyler. 403 aldıysanız token’ın scopes değerini panelden kontrol edin.

Sırada ne var

• Bir API token ile talep açmanın tüm ayrıntıları: Talep açma
• Talep açıldıktan sonra son kullanıcının kimlik doğrulaması gerektirmeden takip etmesi: Talep takibi
• Endpoint bazlı tam sözleşme: API Referansı