07 — Lisans ve Entitlement Kontrolü
Kimin için: Ücretli SaaS özellikleri, limit kontrolü ve kurumsal lisanslama uygulayan geliştiriciler.
Ön koşul: Temel Kavramlar ve bir App API Key (entitlements.readyetkili).
Tahmini süre: 15 dakika.
Ne Öğreneceksiniz
- Kullanıcının uygulamanıza veya belirli modüllere erişim hakkı olup olmadığını doğrulamayı,
- Bireysel Abonelik vs. Organizasyon Koltuk Lisansı ayrımını,
- Plan özellikleri (
features) ve kotaları (limits) uygulamanızda denetlemeyi, - Yetkisiz kullanıcıları ödeme/yükseltme akışına yönlendirmeyi.
Yetki Doğrulama Akış Mimarisi
Diyagram (Mermaid)
flowchart TD
Request["Kullanıcı İsteği Gelir"] --> HasToken{"Geçerli Access Token Var mı?"}
HasToken -- Hayır --> RedirectLogin["Giriş Sayfasına Yönlendir"]
HasToken -- Evet --> LocalCheck{"Token İçinde Hak Var mı?"}
LocalCheck -- Evet --> Allowed{"allowed == true?"}
LocalCheck -- Hayır / Eskimiş --> CallAPI["GET /api/v1/apps/users/:sub/entitlements"]
CallAPI --> Allowed
Allowed -- Evet --> CheckFeature{"Modül İzni Var mı? (features.includes)"}
Allowed -- Hayır --> UpgradeScreen["Plan Satın Al / Yükselt Ekranı"]
CheckFeature -- Evet --> Proceed["İşleme İzin Ver"]
CheckFeature -- Hayır --> UpgradeScreen
Entitlement Sözleşmesi (`EntitlementContract`)
TALOST ID sisteminde tüm lisans durumları standart bir sözleşme formatında dönülür:
json
{
"allowed": true,
"source": "INDIVIDUAL_SUBSCRIPTION",
"subject": {
"user_id": "usr_94b8e21c-3085-48fa-9549-a1d29381e4ab",
"email": "user@example.com",
"name": "Ali Veli"
},
"subscription": {
"id": "sub_xxxxxxxx",
"status": "ACTIVE",
"plan_code": "pro_monthly",
"plan_name": "Profesyonel Plan",
"starts_at": "2026-10-01T00:00:00.000Z",
"ends_at": "2026-11-01T00:00:00.000Z",
"remaining_days": 27
},
"seat": null,
"features": ["export_pdf", "unlimited_projects", "priority_support"],
"limits": {
"max_seats": 5,
"storage_gb": 100
},
"evaluated_at": "2026-10-04T12:00:00.000Z"
}
Lisans Kaynakları (`source`):
INDIVIDUAL_SUBSCRIPTION: Kullanıcı kendi adına kredi kartı veya havale ile bireysel bir plana abonedir.ORGANIZATION_LICENSE: Kullanıcı bir şirketin üyesidir ve şirket yöneticisi ona bir koltuk lisansı (seat) atamıştır.FREE_APPLICATION: Uygulamanız ücretsiz erişim modelindedir.NONE: Kullanıcının aktif bir lisansı veya aboneliği yoktur (allowed: false).
Kod Örnekleri
Sunucu Taraflı Entitlement Kontrolü (TypeScript / Next.js)
typescript
// lib/entitlements.ts
export interface UserEntitlement {
allowed: boolean;
features: string[];
limits: Record<string, number>;
plan_code?: string;
}
export async function checkUserEntitlement(sub: string): Promise<UserEntitlement> {
const apiKey = process.env.TALOST_APP_API_KEY!; // tlk_live_...
const issuer = process.env.TALOST_ISSUER || "https://id.talost.com";
const res = await fetch(`${issuer}/api/v1/apps/users/${sub}/entitlements`, {
headers: {
"X-Talost-Api-Key": apiKey,
},
next: { revalidate: 300 }, // 5 dakika in-memory önbellek
});
if (!res.ok) {
return { allowed: false, features: [], limits: {} };
}
const data = await res.json();
return {
allowed: data.has_access,
features: data.features || [],
limits: data.limits || {},
plan_code: data.plan?.code,
};
}
// Bir rota içinde koruma örneği:
export async function requireFeature(sub: string, requiredFeature: string) {
const entitlement = await checkUserEntitlement(sub);
if (!entitlement.allowed) {
throw new Error("Lütfen uygulamanızı kullanabilmek için bir plana abone olun.");
}
if (!entitlement.features.includes(requiredFeature)) {
throw new Error(`Bu özelliği (${requiredFeature}) kullanmak için planınızı yükseltmeniz gerekmektedir.`);
}
return true;
}
Sık Yapılan Hatalar
- Lisans kontrolünü yalnızca istemci (tarayıcı) tarafında yapmak: Akıllı bir kullanıcı frontend kodundaki kontrolleri kolayca geçebilir. Kritik API işlemlerinde sunucu tarafında her zaman
featuresvelimitsdenetlenmelidir. - Webhook kullanmadan sınırsız önbellek tutmak: Kullanıcı aboneliğini iptal ettiğinde veya planını yükselttiğinde uygulamanızın hemen haberdar olması için Webhook'ları (09) entegre edin ve önbelleği geçersiz kılın.
İlgili Sayfalar
Son doğrulama: 2026-10-04 · Kaynak: _envanter.md, src/lib/billing/entitlement-contract.ts
Son doğrulama: 2026-10-04 · Kaynak: `_envanter.md`, `src/lib/billing/entitlement-contract.ts`