Kimlik Doğrulama
Müşteri uygulaması şifresiz kayıt ve giriş akışlarını kullanır. API anahtarı, kurum adına otomatik entegrasyon içindir; JWT ise doğrulanmış kullanıcının oturumunu temsil eder. Kimlik doğrulamasız açık arşiv yolları ayrıca tanımlıdır.
Alan adları ve oturum sınırı
| Adres | Kullanım |
|---|---|
https://mevzuatradar.com | Tanıtım ve herkese açık sayfalar |
https://app.mevzuatradar.com/register | Müşteri ve davetli kullanıcı kaydı |
https://app.mevzuatradar.com/login | Müşteri girişi |
https://mevzuatradar.com/admin | Platform yönetimi |
https://api.mevzuatradar.com | API temel adresi |
Kök alan adındaki müşteri yolları uygulama alan adına yönlenir. Uygulama
alan adındaki herkese açık sayfalar ve /admin yolları kök alan adına döner.
/login?source=admin veya yönetim yolunu hedefleyen callbackUrl ayrı yönetim
girişi olarak ele alınır. source=admin dışındaki giriş akışı /admin yoluna
dönemez; güvenli varsayılan hedef /feed olur. Kurum ADMIN rolü, platform
yöneticisi yetkisi değildir.
Şifresiz kayıt
Normal kayıt e-posta ve telefon doğrulamasını gerektirir:
| Yöntem ve yol | İstek ve sonuç |
|---|---|
POST /auth/register/otp/request | target: "email" ile email, target: "phone" ile phone gönderilir. Gerektiğinde botToken ve yeniden gönderimde resend kullanılır. Yanıt challengeId, target, expiresAt, canResendAt, channel, maskedDestination içerir. |
POST /auth/register/otp/verify | challengeId ve otp gönderilir; verified: true, verificationToken, purpose döner. Her iletişim kanalı ayrı doğrulanır. |
POST /auth/register | email, phone, name ve doğrulama sonuçlarından alınan emailOtpVerificationToken, phoneOtpVerificationToken gönderilir. organizationName isteğe bağlıdır. Davet kaydında invitationToken kullanılır; e-posta OTP’si yerine davet kanıtı geçer. |
POST /auth/session/bootstrap | Kayıt yanıtındaki sessionBootstrapToken, gövdede token alanıyla tek kullanımlık olarak gönderilir; kullanıcı oturumu açılır. |
Kayıt yanıtındaki nextPath, uygulamanın sonraki adımını belirtir. OTP kodları
kayıt isteğine doğrudan taşınmaz; doğrulama yanıtındaki token’lar kullanılır.
Risk değerlendirmesi ek doğrulama isteyebilir. Tarayıcı kayıt akışı bu adımları
ve oturum başlatmayı yönetir.
OTP ile giriş ve JWT alma
Auth yollarında /api/v1 öneki yoktur. Aşağıdaki yollar API temel adresine
eklenir; başarılı JSON yanıtları { success: true, data: ... } zarfındadır.
| Yöntem ve yol | İstek alanları |
|---|---|
POST /auth/login/otp/request | Zorunlu identifier (e-posta veya telefon, 3–255 karakter); isteğe bağlı scope (app veya admin), botToken, deviceHint, resend |
POST /auth/login/otp/verify | Zorunlu challengeId (16–128 karakter), otp (4–8 rakam); isteğe bağlı responseMode: "SESSION_HANDOFF", deviceHint |
OTP isteme yanıtının data alanı şunları içerir:
type LoginOtpRequestData = {
accepted: true;
sent: boolean;
message: string;
challengeId: string | null;
expiresAt: string;
canResendAt: string;
channel: 'EMAIL' | 'SMS';
maskedDestination: string;
};accepted: true tek başına kod gönderildiği anlamına gelmez. Müşteri
kapsamında kayıtlı aktif hesap bulunamazsa sent: false ve challengeId: null
döner; kod gönderilmez. Süre ve yeniden gönderim için sunucunun döndürdüğü
expiresAt / canResendAt kullanılır. Bot doğrulama politikası ve istek
sınırları geçerlidir; DTO’da botToken alanının isteğe bağlı olması her
koşulda tokensız istek kabul edileceği anlamına gelmez.
scope: "admin" yalnız e-posta kabul eder. Aktif platform yöneticisi hesabı,
platform yöneticisi kurum işareti ve izinli e-posta koşulları sağlanmazsa
403 döner; normal müşteri kapsamındaki sent: false davranışı uygulanmaz.
OTP doğrulamasında responseMode gönderilmezse başarılı yanıt
{ success: true, data: { accessToken, user } } olur. Bu JWT, yetki gerektiren
API isteklerinde şu başlıkla kullanılır:
Authorization: Bearer <accessToken>Tarayıcı akışı responseMode: "SESSION_HANDOFF" kullanabilir. Bu durumda
data.state: "SESSION_READY" ile sessionBootstrapToken ve nextPath içeren
oturum başlatma sonucu döner; bu token doğrudan API erişim JWT’si değildir.
POST /auth/session/bootstrap değişimiyle oturum açılır. Müşteri arayüzü
NextAuth oturumunu bu akış üzerinden yönetir.
E-posta bağlantısı veya koduyla giriş
POST /auth/magic/request zorunlu email ve isteğe bağlı botToken,
deviceHint, resend alır. Uygun hesap ve etkinleştirme politikası varsa
aynı e-postada magic link ve tek kullanımlık kod gönderilir. sent alanı
kontrol edilir; hesap bulunmaması veya özelliğin kurumda etkin olmaması
başarılı gönderim gibi yorumlanmaz.
POST /auth/magic/verify isteğinde email ile birlikte token veya otp
gerekir. İkisi birden gönderilirse kod kullanılır. İsteğe bağlı
responseMode: "SESSION_HANDOFF" tarayıcı oturum başlatma sonucunu seçer;
gönderilmezse başarılı sonuç accessToken ve user içerir. Bağlantı ve kod
süreli ve tek kullanımlıktır; yeniden gönderim önceki magic challenge’ı
geçersiz kılar.
Oturum yenileme ve çıkış
POST /auth/session/refresh: mevcut geçerli JWT ile oturum yenilenir.POST /auth/logout: mevcut oturum kapatılır. Tarayıcıdaki oturum temizliği uygulamanın çıkış akışıyla yapılır.
Bu yollar kalıcı entegrasyon anahtarı üretmez. Uzun süre çalışan entegrasyonlar kullanıcı OTP’sini otomatik toplamaya çalışmak yerine API anahtarı kullanır.
API anahtarı oluşturma ve yönetme
API ayarları kurum ADMIN rolünü
ve planın Genel API erişimini gerektirir. Yönetim API’si JWT ile çalışır:
| Yöntem ve yol | Sayfa izni | Amaç |
|---|---|---|
GET /api/v1/api-keys | settings:read | Anahtarları listeleme |
GET /api/v1/api-keys/:id | settings:read | Anahtar ayrıntısı |
POST /api/v1/api-keys | settings:write | Anahtar oluşturma |
PUT /api/v1/api-keys/:id | settings:write | Ad, izin ve izinli IP listesini güncelleme |
POST /api/v1/api-keys/:id/rotate | settings:write | Anahtarı yenileme |
POST /api/v1/api-keys/:id/revoke | settings:write | Anahtarı iptal etme |
GET /api/v1/api-keys/:id/usage | settings:read | Kullanım istatistikleri |
Oluşturma gövdesi:
| Alan | Kural |
|---|---|
name | Zorunlu, 3–120 karakter |
permissions | Zorunlu, boş olmayan, benzersiz katalog izinleri dizisi; DTO üst sınırı 10 öğe |
expiresAt | İsteğe bağlı ISO tarih; gelecekte olmalı. Gönderilmezse süre sınırı atanmaz. |
allowedIps | İsteğe bağlı, en fazla 50 benzersiz IPv4/IPv6 adresi; CIDR aralığı değildir. Boşsa IP kısıtı uygulanmaz. |
Anahtar biçimi mr_live_ ve ardından 48 onaltılık karakterdir. Oluşturma ve
yenileme yanıtında data.key ile revealedOnce: true döner; liste ve ayrıntı
yanıtından anahtarın tamamı geri alınamaz. Yenilemede önceki değer için en fazla 24
saatlik geçiş süresi tanınır; iptal, önceki değerin geçerliliğini de kaldırır.
Genel API isteği örneği:
curl -sS "https://api.mevzuatradar.com/api/v1/changes" \
-H "x-api-key: $MEVZUATRADAR_API_KEY"GET /api/v1/changes gibi entegrasyon yolları API anahtarı veya JWT kabul
eder. GET /api/v1/public/regulations ve GET /api/v1/public/source-stats
yolları kimlik doğrulamasızdır. API anahtarı ve Webhook yönetim yolları ise
JWT gerektirir; x-api-key yeterli değildir.
İzin kataloğu ve uygulanan yetkiler
| İzin | Katalog kapsamı | Yalnız ENTERPRISE |
|---|---|---|
regulations:read | Mevzuat değişikliklerini okuma | Hayır |
search:read | Arama okuma | Hayır |
actions:read | İşlem akışlarını ve yükümlülük vadelerini okuma | Hayır |
actions:write | İşlem akışı yazma | Evet |
verification:read | Doğrulama raporlarını okuma | Evet |
reports:read | Yönetim kurulu raporlarını okuma | Evet |
evidence-packs:read | Kanıt paketlerini okuma | Evet |
webhooks:manage | Webhook yönetimi | Evet |
people:read | Kişi bilgilerini okuma (ad ve e-posta) | Hayır |
people:read kişisel veri paylaşımı için açık seçimdir; yeni anahtarlarda
varsayılan olarak seçilmez. İzin yoksa aksiyon ve son tarih yanıtlarında
assignee, kurul raporlarında createdBy alanı tamamen çıkarılır (null dönmez).
Mevcut ACTIVE anahtarlar geçiş migration’ıyla bu izni alır; REVOKED ve EXPIRED
anahtarlar değişmez. JWT yanıtları korunur. Bu kapsam müşterinin kendi API
anahtarı içindir; IntegrationApp kişisel veri onayı ayrıca hukuk kaydına bağlıdır.
Bu tablo izin kataloğunu gösterir; her satır bağımsız bir API yolunun veya API
anahtarıyla yazma desteğinin var olduğu anlamına gelmez. Örneğin
POST /api/v1/webhooks JWT + ADMIN + settings:write ister. Katalogdaki
webhooks:manage bu guard zincirini değiştirmez. Plan erişimi, anahtar kotası,
kurum kapsamı ve ilgili yolun sayfa izinleri ayrıca değerlendirilir.
API anahtarının izinleri her istekte mevcut planın izinleriyle kesiştirilir.
Plan düşüşünde Enterprise’a özel bir izinle yapılan çağrı 403 PLAN_FEATURE_UNAVAILABLE
alır; anahtar kaydı değiştirilmez ve plan yeniden yükseltilince izin kendiliğinden döner.
Hatalar ve sırların korunması
400: geçersiz gövde veya alan biçimi; örneğin doğrulamada kod/token eksikliği.401: geçersiz, süresi dolmuş ya da iptal edilmiş kimlik bilgisi.403: rol, sayfa izni, plan, anahtar izni veya IP kısıtı nedeniyle erişim reddi. Arşivli kurumun API anahtarı da403alır:Bu kaynağa erişim izniniz yok.Bu sabit mesaj kurum adı, kimliği veya plan bilgisi içermez. Kurum arşivden çıkarıldığında geçerli olan aynı anahtar tekrar kullanılabilir. Arşivli kurumun webhook uçları bildirim hedeflerine dahil edilmez.429: istek sınırı aşıldı. Genel API anahtarı hız sınırındaRetry-Aftersaniye cinsinden bekleme süresini bildirir.
OTP, magic link, JWT, API anahtarı ve Webhook imzalama sırrı kaynak koduna, dokümana veya log’a yazılmaz. Örneklerdeki ortam değişkeni adları istemci uygulamanın seçtiği adlardır; sunucuda otomatik tanımlanan kimlik bilgileri değildir. API anahtarı yenileme ile Webhook sırrı yenileme ayrı işlemlerdir; Webhook sözleşmesi Webhook Akışı sayfasındadır.
Uygulama ile istek
Entegrasyon uygulaması erişimi kapalı beta kapsamındadır. Canlı kullanım, uygulama onayı ve kurum yöneticisinin verdiği aktif izne bağlıdır. Uygulama sırrını yalnız sunucunuzda saklayın; tarayıcıya, günlüklere ve paylaşılan bağlantılara koymayın.
Sunucudan sunucuya isteklerde X-API-Key başlığına uygulama sırrını,
X-MR-Organization-Id başlığına izin verilen hedef kurum kimliğini gönderin.
Authorization: Bearer <uygulama-sırrı> da desteklenir. Uygulamanın geliştirici
kurumu, hedef kurumun yerine geçmez; her istek aktif kurum iznini yeniden okur.
Yeni sır biçimi mr_app_test_ veya mr_app_live_ öneki ve 48 küçük hex
karakterdir. Test sırrı yalnız sandbox kurumuyla, canlı sır yalnız canlı
kurumuyla eşleşir. Mevcut mr_live_ API anahtarı akışı devam eder.
| HTTP | Kod / durum | Yapılacak işlem |
|---|---|---|
| 401 | INVALID_INTEGRATION_SECRET | Sırrı ve biçimini denetleyin; sır değerini destek talebine eklemeyin. |
| 403 | INTEGRATION_APP_SUSPENDED, INTEGRATION_APP_TERMINATED | Uygulama durumunu inceleyin. |
| 403 | INTEGRATION_ACCESS_DENIED | Kurum başlığını ve kurum iznini denetleyin. Olmayan kurum ve izin aynı yanıtı alır. |
| 403 | INTEGRATION_CONSENT_REVOKED | Kurumun yeni izin vermesi gerekir; iptal edilen izin tekrar kullanılamaz. |
| 403 | INTEGRATION_SCOPE_REQUIRED, PLAN_FEATURE_UNAVAILABLE, LEGAL_REVIEW_REQUIRED | Uç iznini, uygulama kapsamını ve müşteri planını denetleyin. |
| 402 | CUSTOMER_PLAN_REQUIRED | Müşterinin etkin ödeme/plan durumunu denetleyin. |
| 402 | SPONSOR_PAYMENT_REQUIRED | Sponsorlu bağlantıda firmanın kontrat/ödeme durumunu denetleyin; müşteri verisi etkilenmez. |
| 403 | SPONSOR_ENTITLEMENT_REQUIRED | Sponsor firmanın API yetkisini denetleyin. |
| 429 | INTEGRATION_RATE_LIMIT_EXCEEDED, INTEGRATION_QUOTA_EXHAUSTED | Hız sınırında Retry-After kadar bekleyin; aylık kotayı ayrıca inceleyin. |
| 503 | INTEGRATION_DISABLED, RATE_LIMIT_UNAVAILABLE | Geçici kapatmayı veya servis hatasını kontrollü geri çekilmeyle yeniden deneyin. |
Dakikalık uygulama/kurum kovası ile uygulama toplam kovası ayrı sayılır.
Her ikisinde sınır min(müşteri plan sınırı, 600) olur; global güvenlik tier’ı
ayrıca uygulanır.
Ödeyen kuralı. Her istekte önce müşterinin kendi ücretli planı denenir:
müşterinin etkin ve ücretli (deneme olmayan) aboneliği genel API özelliğini
içeriyorsa ödeyen müşteridir. Yoksa uygulamayı sunan firmanın geçerli sponsorlu
anlaşması (yürürlükteki revizyon ve etkin kontrat) aranır; varsa ödeyen
firmadır. İkisi de yoksa 402 CUSTOMER_PLAN_REQUIRED, sponsorlu anlaşma var
ama geçerli değilse 402 SPONSOR_PAYMENT_REQUIRED döner. Bağlantı başına
ayrı bir ödeme bayrağı yoktur.
Vade ve ek süre. Sponsor firmanın ödenmemiş dönem faturası, vade +
anlaşmadaki ek süre (varsayılan 30 + 14 gün, Türkiye saati) dolana kadar
bağlantıyı kapatmaz. Ek süre dolduğunda yalnız sponsorlu çağrılar
402 SPONSOR_PAYMENT_REQUIRED alır ve sponsorlu webhook teslimleri iptal
edilir (ödeme sonrası toplu gönderim yoktur); ödeme kaydedildiğinde erişim
hemen açılır.
Kota sahipliği. Aylık kullanım ödeyenin faturalama kurumuna bir kez
yazılır; veri her zaman hedef müşteri kurumundan okunur. Sponsorlu bağlantıda
kullanılabilir izinler uygulama kapsamı ile sponsor firmanın plan yetkisinin
kesişimidir. Ödeyen havuzu bitince 429 INTEGRATION_QUOTA_EXHAUSTED döner.
İz metadata’sı appId, grantId, customerOrgId içerir; ham sır içermez.
Bir çağrı yalnız bir kez sayılır. Her çağrı için ayrı denetim kaydı oluşturulmaz;
izin iptali gibi kritik yaşam döngüsü işlemleri denetlenir.
Efektif izin, kurum izni ∩ uygulamanın onaylı kapsamı ∩ müşteri planıdır.
people:read yokken kişi alanları yanıta eklenmez; kapsamın verilebilmesi
hukuk doğrulamasına bağlıdır. Arşivlenmiş kurum erişimi reddedilir ve izni
SYSTEM olarak iptal edilir. Uygulamanın askıya alınması iznini silmez.