Ana içeriğe geç
Mevzuat RadarDokümantasyon
Uygulamaya git ↗

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ı

AdresKullanım
https://mevzuatradar.comTanıtım ve herkese açık sayfalar
https://app.mevzuatradar.com/registerMüşteri ve davetli kullanıcı kaydı
https://app.mevzuatradar.com/loginMüşteri girişi
https://mevzuatradar.com/adminPlatform yönetimi
https://api.mevzuatradar.comAPI 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/requesttarget: "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/verifychallengeId ve otp gönderilir; verified: true, verificationToken, purpose döner. Her iletişim kanalı ayrı doğrulanır.
POST /auth/registeremail, 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/bootstrapKayı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/requestZorunlu identifier (e-posta veya telefon, 3–255 karakter); isteğe bağlı scope (app veya admin), botToken, deviceHint, resend
POST /auth/login/otp/verifyZorunlu 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 yolSayfa izniAmaç
GET /api/v1/api-keyssettings:readAnahtarları listeleme
GET /api/v1/api-keys/:idsettings:readAnahtar ayrıntısı
POST /api/v1/api-keyssettings:writeAnahtar oluşturma
PUT /api/v1/api-keys/:idsettings:writeAd, izin ve izinli IP listesini güncelleme
POST /api/v1/api-keys/:id/rotatesettings:writeAnahtarı yenileme
POST /api/v1/api-keys/:id/revokesettings:writeAnahtarı iptal etme
GET /api/v1/api-keys/:id/usagesettings:readKullanım istatistikleri

Oluşturma gövdesi:

AlanKural
nameZorunlu, 3–120 karakter
permissionsZorunlu, 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

İzinKatalog kapsamıYalnız ENTERPRISE
regulations:readMevzuat değişikliklerini okumaHayır
search:readArama okumaHayır
actions:readİşlem akışlarını ve yükümlülük vadelerini okumaHayır
actions:writeİşlem akışı yazmaEvet
verification:readDoğrulama raporlarını okumaEvet
reports:readYönetim kurulu raporlarını okumaEvet
evidence-packs:readKanıt paketlerini okumaEvet
webhooks:manageWebhook yönetimiEvet
people:readKiş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ı da 403 alı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ında Retry-After saniye 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.

HTTPKod / durumYapılacak işlem
401INVALID_INTEGRATION_SECRETSırrı ve biçimini denetleyin; sır değerini destek talebine eklemeyin.
403INTEGRATION_APP_SUSPENDED, INTEGRATION_APP_TERMINATEDUygulama durumunu inceleyin.
403INTEGRATION_ACCESS_DENIEDKurum başlığını ve kurum iznini denetleyin. Olmayan kurum ve izin aynı yanıtı alır.
403INTEGRATION_CONSENT_REVOKEDKurumun yeni izin vermesi gerekir; iptal edilen izin tekrar kullanılamaz.
403INTEGRATION_SCOPE_REQUIRED, PLAN_FEATURE_UNAVAILABLE, LEGAL_REVIEW_REQUIREDUç iznini, uygulama kapsamını ve müşteri planını denetleyin.
402CUSTOMER_PLAN_REQUIREDMüşterinin etkin ödeme/plan durumunu denetleyin.
402SPONSOR_PAYMENT_REQUIREDSponsorlu bağlantıda firmanın kontrat/ödeme durumunu denetleyin; müşteri verisi etkilenmez.
403SPONSOR_ENTITLEMENT_REQUIREDSponsor firmanın API yetkisini denetleyin.
429INTEGRATION_RATE_LIMIT_EXCEEDED, INTEGRATION_QUOTA_EXHAUSTEDHız sınırında Retry-After kadar bekleyin; aylık kotayı ayrıca inceleyin.
503INTEGRATION_DISABLED, RATE_LIMIT_UNAVAILABLEGeç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.