TALOST ID Ekosistem Envanteri (`_envanter.md`)
Bu dosya, TALOST ID geliştirici rehberinin (
docs/rehber/) tek ve kesin doğruluk kaynağıdır.
Rehberde yer alan tüm uç noktalar, parametreler, claim'ler, webhook olayları ve hata kodları doğrudan bu envanterden türetilmiştir. Kodda karşılığı olmayan hiçbir özellik rehbere kesin bilgi olarak yazılamaz (yalnızca "Planlanıyor" notuyla belirtilebilir).
Son doğrulama: 2026-10-04 · Kaynak: TALOST ID v1.0.0 codebase (src/app/**, src/lib/**)
1. Uç Nokta (Endpoint) Envanteri
1.1 OIDC & OAuth 2.0 Uç Noktaları
| Uç Nokta | Metot | Kimlik Doğrulama | Parametreler | Yanıt / Format | Hata Kodları | Kaynak Dosya |
|---|---|---|---|---|---|---|
/.well-known/openid-configuration |
GET |
Anonim | Yok | JSON OIDC Discovery dokümanı | - | src/app/.well-known/openid-configuration/route.ts |
/oauth/jwks.json |
GET |
Anonim | Yok | JSON RFC 7517 JWK Set (keys: RS256 public keys) |
500 | src/app/oauth/jwks.json/route.ts |
/oauth/authorize |
GET |
Kullanıcı Oturumu (Cookie) | client_id, redirect_uri, response_type=code, scope, state, code_challenge, code_challenge_method=S256 |
302 Redirect (?code=...&state=...) |
invalid_request, unauthorized_client, access_denied, maintenance_mode |
src/app/oauth/authorize/route.ts |
/oauth/token |
POST |
client_secret_basic, client_secret_post veya public client PKCE |
grant_type (authorization_code veya refresh_token), client_id, client_secret (confidential ise), code, code_verifier, redirect_uri, refresh_token |
JSON: access_token, token_type: "Bearer", expires_in: 3600, id_token, refresh_token, scope |
invalid_request, invalid_client, invalid_grant, unsupported_grant_type |
src/app/oauth/token/route.ts |
/oauth/userinfo |
GET, POST |
Bearer Token (access_token) |
Yok | JSON OIDC claims (sub, email, name, subscription vb.) |
401 Unauthorized (invalid_token), 403 Forbidden |
src/app/oauth/userinfo/route.ts |
/oauth/revoke |
POST |
client_secret_basic / client_secret_post |
token, token_type_hint (access_token veya refresh_token) |
HTTP 200 OK { success: true } |
invalid_client, invalid_request |
src/app/oauth/revoke/route.ts |
/oauth/logout |
GET, POST |
İsteğe bağlı id_token_hint |
id_token_hint, post_logout_redirect_uri, state |
302 Redirect veya oturum sonlandırma sayfası | invalid_request |
src/app/oauth/logout/route.ts |
/panel/uygulamalar/[slug]/sso |
GET |
Kullanıcı Oturumu (Cookie) | Route param: [slug] |
302 Redirect (Uygulamanın DEV/STG/PROD istemcisine tek tıkla doğrudan giriş) | 404 Not Found, 403 Forbidden | src/app/panel/uygulamalar/[slug]/sso/route.ts |
1.2 Uygulama Yönetim API'leri (`/api/v1/apps/**`)
Uygulama sunucularının TALOST ID ile haberleşmesi için kullanılır.
Kimlik Doğrulama: X-Talost-Api-Key: tlk_... başlığı veya Authorization: Bearer tlk_....
| Uç Nokta | Metot | Zorunlu API Key Scope | Parametreler / Gövde | Yanıt Alanları | Hata Kodları | Kaynak Dosya |
|---|---|---|---|---|---|---|
/api/v1/apps/me |
GET |
heartbeat |
Yok | app: { id, slug, name, status, access_model }, key: { name, environment, scopes } |
401, 403, 429 | src/app/api/v1/apps/me/route.ts |
/api/v1/apps/status |
GET |
heartbeat |
Yok | app_status, maintenance: { active, message, ends_at }, announcements: [], versions: Record<platform, VersionInfo> |
401, 403 | src/app/api/v1/apps/status/route.ts |
/api/v1/apps/version-check |
GET |
Anonim (IP Rate Limit: 60/dk) | Query: client_id, platform, version |
latest_version, min_supported_version, update_available, forced_update, download_url |
400, 404, 429 | src/app/api/v1/apps/version-check/route.ts |
/api/v1/apps/heartbeat |
POST |
heartbeat |
JSON: platform, version, instance_id, status (OK, DEGRADED, ERROR), details? (max 4KB) |
ok: true, next_in_seconds: 60 |
400, 401, 403, 429 | src/app/api/v1/apps/heartbeat/route.ts |
/api/v1/apps/config |
GET |
config.read |
Header: If-None-Match (opsiyonel) |
200 JSON `{ version, entries: Record<string, string | number | boolean |
/api/v1/apps/flags/evaluate |
GET |
config.read |
Query: user_id (kullanıcı sub değeri) |
JSON: { flags: Record<string, boolean> } |
400, 401, 403 | src/app/api/v1/apps/flags/evaluate/route.ts |
/api/v1/apps/users/[sub]/entitlements |
GET |
entitlements.read |
Route: [sub] |
JSON: sub, has_access, plan: { id, code, name }, subscription, features, limits |
401, 403, 404 | src/app/api/v1/apps/users/[sub]/entitlements/route.ts |
1.3 Faturalandırma ve Doğrulama API'leri
| Uç Nokta | Metot | Kimlik Doğrulama | Parametreler | Yanıt | Kaynak Dosya |
|---|---|---|---|---|---|
/api/v1/billing/checkout |
POST |
Kullanıcı Oturumu veya Bearer Token | app_slug, plan_code, billing_cycle (MONTHLY/YEARLY), success_url, cancel_url |
{ checkout_url, session_id } |
src/app/api/v1/billing/checkout/route.ts |
/api/v1/billing/payments/[id]/status |
GET |
Kullanıcı Oturumu / Bearer | Route: [id] |
{ payment_id, status, amount, currency } |
src/app/api/v1/billing/payments/[id]/status/route.ts |
/api/v1/entitlements/verify |
POST |
Bearer Token / API Key | { user_id, app_id, feature? } |
EntitlementContract JSON | src/app/api/v1/entitlements/verify/route.ts |
2. Token Ömürleri ve Türleri
| Token Türü | Format / Algoritma | Geçerlilik Süresi | Saklama Önerisi | Doğrulama Yöntemi |
|---|---|---|---|---|
| Access Token | JWT / RS256 (typ: at+jwt) |
15 dakika (900 sn) | Sunucu: Bellek / Şifreli HttpOnly Çerez | JWKS ile yerel doğrulama (/oauth/jwks.json) |
| ID Token | JWT / RS256 (typ: JWT) |
1 saat (3600 sn) | Sunucu oturumu | JWKS ile imza, iss, aud, nonce kontrolü |
| Refresh Token | Opak Kriptografik Dize | 30 gün | Sunucu tarafı güvenli veritabanı | /oauth/token (grant_type=refresh_token) |
| Authorization Code | Opak Tek Kullanımlık Dize | 5 dakika (300 sn) | Bellek / Geçici Önbellek | Yalnızca bir kez token takasında takas edilir |
| PKCE code_verifier | 43-128 Karakter Dize | Akış süresince (5 dk) | İstemci oturumu / HttpOnly Çerez | SHA-256 base64url özeti code_challenge ile karşılaştırılır |
3. Scope → Claim Eşleşme Tablosu
| Scope | Sağlanan Claim'ler | Açıklama |
|---|---|---|
openid |
sub, iss, aud, exp, iat |
OIDC kimlik belirteci ve temel süre bilgileri. sub kullanıcının değişmez evrensel UUID'sidir. |
profile |
name, given_name, family_name, preferred_username, picture, locale |
Kullanıcının ad-soyadı, kullanıcı adı ve profil avatar bağlantısı. |
email |
email, email_verified |
Kullanıcının doğrulanmış e-posta adresi ve doğrulama durumu boolean değeri. |
offline_access |
refresh_token |
Token yanıtında refresh token üretilmesini sağlar. |
subscription |
subscription: { status, plan_code, plan_name, ends_at } |
Kullanıcının bu uygulamadaki aktif abonelik ve lisans özeti. |
4. Webhook Olay Kataloğu
Webhook yükleri istemciye POST isteği ile gönderilir.
İmza Başlığı: X-Talost-Signature: t=1728000000,v1=64_karakter_hex_hmac_sha256
İmza Hesabı: HMAC_SHA256(secret, t + "." + rawBody)
Zaman toleransı: 300 saniye (5 dakika)
Yeniden deneme (backoff): [60, 300, 1800, 7200, 43200] saniye (5 deneme). 10 saniye zaman aşımı.
Olay Tipi (type) |
Kategori | Açıklama | Tipik Veri Alanları (data) |
|---|---|---|---|
subscription.activated |
Abonelik | Yeni abonelik başlatıldı | subscription_id, user_id, plan_code, status, starts_at |
subscription.renewed |
Abonelik | Dönemlik abonelik yenilendi | subscription_id, user_id, plan_code, current_period_end |
subscription.canceled |
Abonelik | Abonelik dönem sonu iptal edildi | subscription_id, user_id, cancel_at_period_end: true |
subscription.expired |
Abonelik | Abonelik süresi doldu | subscription_id, user_id, expired_at |
subscription.plan_changed |
Abonelik | Plan yükseltildi veya düşürüldü | subscription_id, user_id, old_plan_code, new_plan_code |
payment.succeeded |
Ödeme | Ödeme başarıyla tahsil edildi | payment_id, amount, currency, user_id, provider |
payment.refunded |
Ödeme | Ödeme iade edildi | payment_id, refund_amount, reason |
user.updated |
Kullanıcı | Kullanıcı profili değişti | user_id, email, name |
user.suspended |
Kullanıcı | Kullanıcı askıya alındı | user_id, reason |
user.deleted |
Kullanıcı | Kullanıcı hesabı silindi (KVKK/GDPR) | user_id |
session.revoked |
Oturum | Kullanıcı oturumları sonlandırıldı | user_id, revoked_at |
seat.assigned |
Koltuk | Organizasyonda koltuk lisansı verildi | organization_id, user_id, seat_id |
seat.revoked |
Koltuk | Kullanıcıdan koltuk lisansı alındı | organization_id, user_id |
app.maintenance.started |
Bakım | Uygulama bakım moduna girdi | app_id, message, expected_end_at |
app.maintenance.ended |
Bakım | Uygulama bakımdan çıktı | app_id, ended_at |
webhook.test |
Teşhis | Test amaçlı ping olayı | test: true, sent_at |
5. Hata Kodları Sözlüğü (`explainOAuthError`)
| Hata Kodu | Başlık | Temel Nedenler | Çözüm Önerisi |
|---|---|---|---|
invalid_request |
Geçersiz İstek | Eksik zorunlu parametre, PKCE S256 eksik, hatalı Content-Type | Parametreleri, PKCE code_challenge üretimini kontrol edin |
unauthorized_client |
Yetkisiz İstemci | Pasif istemci, DEV/STAGING ortama yetkisiz hesapla giriş | İstemci durumunu aktife alın, ekip üyeliğini teyit edin |
invalid_client |
Geçersiz İstemci Kimlik Bilgileri | Hatalı client_secret, eksik secret | Secret değerini panelden yenileyip env'e ekleyin |
invalid_grant |
Geçersiz Yetki Belgesi | Kodu süresi doldu (5 dk), tekrar kullanılan kod, hatalı PKCE verifier | Yeni akış başlatın, verifier S256 base64url eşleşmesini kontrol edin |
unsupported_response_type |
Desteklenmeyen Yanıt Türü | response_type değeri 'code' dışında |
Yalnızca response_type=code kullanın |
unsupported_grant_type |
Desteklenmeyen Yetki Türü | grant_type değeri geçersiz |
Yalnızca authorization_code veya refresh_token kullanın |
invalid_scope |
Geçersiz Kapsam | Tanımsız veya istemciye atanmamış scope | Desteklenen: openid, profile, email, offline_access |
access_denied |
Erişim Reddedildi | Aktif plan yok, kapalı beta engeli, bakım modu | Kullanıcının plana abone olmasını sağlayın |
rate_limit_exceeded |
İstek Sınırı Aşıldı | Aşırı istek gönderildi | İstek sıklığını azaltın, 1 dakika bekleyin |
maintenance_mode |
Bakım Modu | Uygulama bakım modunda | Bakımın bitiş saatini bekleyin veya admin panelinden sonlandırın |
server_error |
Sunucu Hatası | Sunucu tarafında istisna veya veritabanı kesintisi | /admin/saglik sayfasını kontrol edin |
temporarily_unavailable |
Geçici Olarak Kullanılamıyor | Sunucu geçici aşırı yük altında | Bir süre sonra tekrar deneyin |
Son doğrulama: 2026-10-04 · Kaynak: TALOST ID v1.0.0 codebase (`src/app/**`, `src/lib/**`)