TALOST ID Geliştirici Rehberi

Kimin için: TALOST ID ile entegre olan web, mobil, masaüstü veya API geliştiren yazılımcılar ve AI ajanları.
Ön koşul: Temel OAuth 2.0 / OIDC ve HTTP API bilgisi.
Tahmini süre: Hızlı başlangıç için 15 dakika; kapsamlı entegrasyon için 2–3 saat.

Hoş geldiniz! Bu rehber, uygulamanıza TALOST ID ile tek oturum açma (SSO), lisans ve abonelik doğrulama, webhook entegrasyonu, uzaktan konfigürasyon ve operasyonel sağlık izleme yeteneklerini kazandırmak için hazırlanan resmi ve tek doğruluk kaynağıdır.

🗺️ Rehber Haritası ve Okuma Sırası

Aşağıdaki sıra, sıfırdan bir uygulama geliştirirken veya mevcut bir uygulamayı TALOST ID ekosistemine dahil ederken önerilen adımdır:

1. Temel ve Hazırlık

1. 01. Temel Kavramlar — Kullanıcı, uygulama, ortamlar (DEV/STG/PROD), planlar ve yetkiler (entitlements).
2. 02. Hızlı Başlangıç (15 Dakika) — İlk DEV istemcinizi oluşturun ve Next.js veya Node ile 15 dakikada giriş yapın.
3. 03. Uygulama Kaydı ve Ortamlar — Geliştirici portalında uygulama açma, DEV/STG/PROD istemcileri, redirect URI kuralları.

2. Kimlik Doğrulama (Authentication & OIDC)

4. Giriş Akışları (Platformunuza göre seçin):
   • 04.1. Web Uygulamaları (Sunucu Taraflı) — Next.js, Node.js, Python FastAPI/Django, .NET, PHP (Confidential Client + PKCE).
   • 04.2. SPA ve PWA Uygulamaları — React, Vue, Angular için Public Client + BFF (Backend-for-Frontend) mimarisi.
   • 04.3. Masaüstü Uygulamaları — Electron, WPF, MAUI için sistem tarayıcısı + Loopback (http://127.0.0.1:port) akışı.
   • 04.4. Mobil Uygulamaları — iOS (ASWebAuthenticationSession) ve Android (Custom Tabs) ile Custom URI Scheme / App Links.
   • 04.5. Tek Tıkla Doğrudan Giriş (Direct Login SSO) — TALOST ID Kullanıcı Paneli üzerinden IdP-initiated doğrudan giriş.
5. 05. Tokenlar, Oturum ve Yenileme — Access token, ID token, refresh token döngüsü, JWKS doğrulaması ve güvenli saklama.
6. 06. Kullanıcı Bilgisi ve Claimler — sub kalıcı kimliği, profil bilgileri, scope-claim ilişkisi.
7. 12. Güvenli Çıkış (Logout) — Yerel oturum kapatma ve OIDC RP-Initiated Logout (/oauth/logout).

3. Lisans, Abonelik ve Gelir Modeli

8. 07. Lisans ve Entitlement Kontrolü — Kullanıcının uygulamanıza erişim hakkı var mı? Plan özellikleri, limitler ve organizasyon koltukları.
9. 08. Abonelik Satışı ve Ödeme Yönlendirme — Uygulama içinden TALOST ID ödeme sayfasına (/api/v1/billing/checkout) yönlendirme ve geri dönüş.

4. Olaylar ve Yönetilebilirlik API'leri

10. 09. Webhook Yönetimi ve Olaylar — Abonelik başladı/iptal, ödeme başarılı, kullanıcı silindi olayları; HMAC-SHA256 imza doğrulama.
11. 10. Uygulama Yönetim API'si — Heartbeat, status, version-check, uzaktan konfigürasyon ve feature flagler.
12. 11. Bakım Modu ve Zorunlu Güncellemeler — Planlı bakım duyuruları, OAuth kesintisi ve istemci sürüm denetimi.

5. Kalite, Güvenlik ve Canlıya Alma

13. 13. OAuth ve API Hata Kodları Sözlüğü — Tüm hata kodlarının nedenleri ve kesin çözüm adımları.
14. 14. Güvenlik Kuralları (Asla Yapmayın) — Secret sızdırma, PKCE atlama, token loglama gibi kritik güvenlik açıkları ve çözümleri.
15. 15. Arayüz ve Marka Standartları — "TALOST ID ile Giriş Yap" buton tasarımı, logo kullanımı ve hesap menüsü.
16. 16. Test ve Teşhis Araçları — Portal içi entegrasyon teşhis motoru, token inceleyici ve URI doğrulama.
17. 17. Canlıya Alma (Go-Live) Kontrol Listesi — PROD yayınına çıkmadan önce zorunlu 9 aşamalı kapı.
18. 18. @talost/app-sdk ve Starter Şablonları — Resmi TypeScript SDK ve Next.js starter deposu.
19. 19. AI Ajanları ile Entegrasyon — Cursor, Claude veya Copilot gibi AI araçlarına verilecek hazır entegrasyon promptu.

📌 Kod Envanteri ve Doğruluk Güvencesi

Bu dokümantasyonda geçen tüm endpoint'ler, parametreler ve modeller _envanter.md dosyasında listelenmiştir:

• Tüm Uç Noktalar ve Envanter Tablosu

Son doğrulama: 2026-10-04 · Kaynak: TALOST ID Core Team