Auth API

Auth API, Alaf Server'ın kullanıcıları oturum açtırması ve oturumlarını sürdürme şeklidir. Buradaki hemen hemen her şey, tek bir catch-all aracılığıyla Better Auth tarafından sunulur — e-posta/şifre ile oturum açma ve kaydolma, OAuth, organizasyon/üye/davetiye endpoint'leri ve MCP OAuth yetkilendirme sunucusu. Küçük bir yalnızca masaüstü endpoint kümesi, sıfır-auth yerel bir oturumu başlatmak ve bulut oturum açmayı indirilebilir uygulamaya devretmek için bunun önünde yer alır.

Bu modül neredeyse tamamen dashboard (ve masaüstü modunda, Electron host) tarafından tüketilir — nadiren doğrudan çağırırsınız. Programatik API erişimi için bunun yerine kişisel bir erişim token'ı oluşturun (alaf server token create) ve bunu bir bearer header olarak kullanın. Tam model için API genel bakışı ve Auth & oturumlar bölümlerine bakın.

Endpoint'ler

Bunlar, izin etiketli güvenli rotalar değil, düz Hono rotalarıdır. "Auth" sütunu, bir resource:action etiketi yerine her birinin nasıl korunduğunu gösterir.

Better Auth catch-all

Son rota olan GET|POST /api/auth/*, ham isteği Better Auth'un işleyicisine iletir. Normal bir oturum açma akışının ihtiyaç duyduğu her şey burada bulunur — bu modülde ayrı bir şema yoktur çünkü Better Auth, istek ve yanıt şekillerine sahiptir. Hizmet verdiği endpoint'ler (tümü /api/auth altında) şunları içerir:

• Kimlik Bilgileri — POST /sign-in/email, POST /sign-up/email, POST /sign-out, POST /forget-password, POST /reset-password, POST /verify-email. Şifreler 8–128 karakterdir; sıfırlama ve doğrulama e-postaları yalnızca SMTP yapılandırıldığında gönderilir.
• OAuth — GitHub ve Google için POST /sign-in/social ve GET /callback/:provider (her biri yalnızca istemci ID/secret'ı ayarlandığında etkinleştirilir).
• Organizasyonlar — /organization/*: oluşturma, set-active, list, invite-member, accept-invitation, update-member-role, remove-member, leave ve daha fazlası. Üye listeleme okumaları ayrıca kısıtlı/üye rollerinin yönetici düzeyindeki verileri okuyamaması için korunmuştur.
• MCP OAuth 2.1 — /mcp/authorize, /mcp/token, /mcp/register (dinamik istemci kaydı), /mcp/get-session, ayrıca /.well-known/oauth-authorization-server ve /.well-known/oauth-protected-resource adreslerinde keşif (ayrıca origin root'ta yeniden sunulur). MCP API bölümüne bakın.

Mevcut oturumu al

GET /api/auth/get-session

Etkin oturumu ve kullanıcıyı JSON olarak döndürür veya kimlik doğrulaması yapılmadığında 401 döndürür. Sıfır-auth masaüstü modunda (self-hosted onboarding, şifresiz), bir eksiklik satır içi bir başlatmayı tetikler: Alaf Server yerel yönetici kullanıcısını sağlar, bir oturum oluşturur, yanıt üzerinde çerezi ayarlar ve onu döndürür — böylece dashboard'un ilk navigasyonu /login'e döngü yapmak yerine başarılı olur.

curl https://your-host/api/auth/get-session \
  -H "Cookie: alaf server.session_token=<session>"

Masaüstü oturum başlatma

GET /api/auth/desktop-login, sıfır-auth yerel yönetici için bir oturum oluşturur ve dashboard'a yönlendirir. Self-hosted onboarding tamamlandıktan hemen sonra bir kez çağrılır; eğer örnek sıfır-auth modunda değilse, bunun yerine /login'e yönlendirir. İstek gövdesi yok.

Bulut oturum açma devri (masaüstü)

İndirilebilir uygulama "Cloud ile" oturum açtığında, Electron host bir PKCE akışı çalıştırır ve API buna aracılık eder. Sıra şöyledir: nonce'ı kaydet, sistem tarayıcısını aç, sorgula, ardından talep et.

POST /api/auth/desktop-auth-start

Dahili paylaşılan-token middleware tarafından korunur — yalnızca Electron host bir nonce kaydedebilir. Satır içi doğrulanır (auth için TypeBox şema modülü yoktur); her üç alan da gerekli dizelerdir:

Kalan adımlar gövde değil, sorgu parametreleri alır:

• GET /api/auth/cloud-callback?code=<code>&state=<state> — bulut sağlayıcısı buraya yönlendirir. state ile masaüstü PKCE değişimini çalıştırır ve bekleyen nonce'ı çözer; state olmadan daha basit tarayıcı değişimini çalıştırır ve çerezi doğrudan ayarlar. code gereklidir.
• GET /api/auth/desktop-auth-poll?nonce=<nonce> — Electron, durum resolved olana kadar sorgular, ardından talep URL'sini açar. nonce gereklidir.
• GET /api/auth/desktop-claim?code=<code> — tek kullanımlık talep kodunu bir oturum çereziyle (sürümler arası Electron güvenilirliği için Set-Cookie başlığı aracılığıyla ayarlanır) değiştirir ve dashboard'a yönlendirir. code gereklidir.

Görebileceğiniz hatalar