API Dokümantasyonu

Servisin ayakta olup olmadığını döner

{ "status": "ok", "service": "atlas" }
// auth-api → { "status": "ok", "service": "atlas-auth" }

curl http://localhost:20000/health

Hibrit kimlik doğrulama: yerel DB → kullanıcı yoksa veya hash uyuşmazsa Bandırma ÜniAPI

{
  "username": "berkeergocun@ogr.bandirma.edu.tr",
  "password": "••••••"
}

{
  "valid": true,
  "authorized": true,
  "user_id": "uuid",
  "username": "…",
  "email": "…"
}

• valid=false → kimlik hatalı (200 döner, gövdede valid:false)
• Yerel parola hash’i uyuşmazsa Atlas ÜniAPI’ye fallback yapar; doğrulama başarılıysa yerel hash otomatik yenilenir
• authorized=false → kimlik doğru ama panele yetkisi yok (tablo boşsa herkes yetkili — bootstrap modu)

curl -X POST http://localhost:20005/api/v1/auth/verify \
  -H "X-API-Key: $FRONTEND_API_KEY" -H "Content-Type: application/json" \
  -d '{"username":"user@ogr.bandirma.edu.tr","password":"secret"}'

Kimlik doğrular ve merkezi oturum açar (dış uygulamalar için)

{ "username": "10651974520", "password": "••••••" }

{
  "token": "64-hex-opaque-token",
  "expires_at": "2026-07-24T10:00:00Z",
  "authorized": false,
  "user": { "id": "uuid", "username": "…", "email": "…" }
}

{ "error": "Kullanıcı adı veya şifre hatalı" }

• Oturum, çağıran uygulama anahtarına bağlanır — token yalnızca o anahtarla doğrulanabilir
• authorized: kullanıcının panele erişim yetkisi (bilgi amaçlı, oturumu etkilemez)

curl -X POST http://localhost:20005/api/v1/auth/login \
  -H "X-API-Key: <uygulama-anahtarı>" -H "Content-Type: application/json" \
  -d '{"username":"user@ogr.bandirma.edu.tr","password":"secret"}'

Opaque oturum token'ını doğrular

{ "token": "64-hex-opaque-token" }

{
  "valid": true,
  "expires_at": "…",
  "user": { "id": "uuid", "username": "…", "email": "…" },
  "access": {
    "application_id": "uuid",
    "is_owner": false,
    "roles": ["viewer"],
    "permissions": ["report:read"]
  }
}

{ "valid": false }

• Token gövdede token alanında veya Authorization: Bearer başlığında gönderilebilir

Token'a ait oturumu iptal eder

{ "token": "64-hex-opaque-token" }

{ "message": "Oturum kapatıldı" }

Bir kullanıcının oturumlarını listeler (yönetim/panel)

{
  "sessions": [
    {
      "id": "uuid", "user_id": "uuid", "application_id": "uuid",
      "ip_address": "…", "user_agent": "…",
      "created_at": "…", "last_seen_at": "…", "expires_at": "…", "revoked_at": null
    }
  ]
}

Belirli bir oturumu iptal eder

No Content

E-posta/parola ile giriş yapar ve GLOBAL oturum cookie’si yazar

{ "email": "user@ogr.bandirma.edu.tr", "password": "…" }

{
  "authenticated": true,
  "authorized": true,
  "expires_at": "…",
  "user": { "id": "uuid", "username": "…", "email": "…" }
}

+ Set-Cookie: atlas_sso=…;
  Domain=.bandirma.edu.tr; HttpOnly; Secure; SameSite=Lax

{ "error": "Kullanıcı adı veya şifre hatalı" }

• authorized kullanıcının panele erişim yetkisidir; SSO oturumu yine de açılır
• Cookie HttpOnly’dir — JavaScript okuyamaz (XSS koruması)

E-posta hesabında kayıtlı passkey olup olmadığını ve WebAuthn seçeneklerini döndürür

{ "email": "user@ogr.bandirma.edu.tr" }

{
  "passkey_available": true,
  "challenge_id": "uuid",
  "public_key": { "challenge": "base64url", "rpId": "atlas.bandirma.edu.tr", "allowCredentials": [] }
}

{ "passkey_available": false }

• Challenge sunucuda tek kullanımlık ve kısa ömürlü saklanır; istemci yalnızca public key seçeneklerini alır
• Kullanıcı bulunamadığında da genel passkey_available:false cevabı döner

WebAuthn assertion cevabını doğrular ve SSO cookie’si yazar

{
  "challenge_id": "uuid",
  "credential": { "id": "…", "rawId": "base64url", "type": "public-key", "response": { "clientDataJSON": "…", "authenticatorData": "…", "signature": "…", "userHandle": "…" } }
}

{ "authenticated": true, "authorized": true, "method": "passkey", "user": { "id": "uuid", "username": "…", "email": "…" } }

{ "error": "Passkey doğrulaması başarısız" }

Geçerli SSO kullanıcısı için passkey kayıt seçeneklerini üretir

{ "challenge_id": "uuid", "public_key": { "challenge": "base64url", "rp": { "id": "atlas.bandirma.edu.tr", "name": "Atlas" }, "user": { "id": "base64url", "name": "…", "displayName": "…" } } }

• Yalnızca mevcut HttpOnly SSO cookie’si olan kullanıcı kendi hesabına passkey ekleyebilir

WebAuthn registration cevabını doğrular ve passkey’i hesaba kaydeder

{ "challenge_id": "uuid", "credential": { "id": "…", "rawId": "base64url", "type": "public-key", "response": { "clientDataJSON": "…", "attestationObject": "…" } } }

{ "created": true }

{ "error": "Passkey kaydı doğrulanamadı" }

Cookie’den kimliği çözer — “bu tarayıcıda kim giriş yapmış?”

{
  "authenticated": true,
  "authorized": true,
  "expires_at": "…",
  "user": { "id": "uuid", "username": "…", "email": "…" }
}

{ "authenticated": false }

• Token sırayla cookie → X-SSO-Token başlığı → gövdedeki token alanından okunur
• Alt alan adındaki uygulamanın backend’i bunu çağırır (yol a)
• ⚠️ Bu yolda uygulama ham SSO token’ını görür ve onunla diğer uygulamalarda kullanıcıyı taklit edebilir — yalnızca güvenilen birinci-taraf uygulamalar için. Üçüncü taraf için redirect akışını kullanın

curl -X POST -H "X-API-Key: $ATLAS_API_KEY" \
  -H "X-SSO-Token: $cookie_degeri" \
  http://localhost:20005/api/v1/auth/sso/session

Redirect akışının giriş kapısı — tek kullanımlık kod üretir

Location: redirect_uri?code=<tek-kullanımlık>&state=…

Location: /login?next=<authorize-url>

{ "error": "redirect_uri bu uygulama için kayıtlı değil" }

• API anahtarı gerektirmez — tarayıcı buraya doğrudan gezinir ve gezinme isteğine başlık eklenemez
• Güvenlik: HttpOnly cookie + uygulamaya kayıtlı redirect_uri beyaz listesi (birebir eşleşme, wildcard yok)
• Kayıtsız adres için yönlendirme yapılmaz, 400 döner — open-redirect koruması

Tek kullanımlık kodu uygulamanın KENDİ oturum token’ıyla değiştirir

{ "code": "…", "redirect_uri": "…" }

{
  "token": "uygulamanın kendi oturum token’ı",
  "expires_at": "…",
  "authorized": true,
  "user": { "id": "uuid", "username": "…", "email": "…" },
  "access": {
    "application_id": "uuid",
    "is_owner": false,
    "roles": ["viewer"],
    "permissions": ["report:read"]
  }
}

{ "error": "Yetkilendirme kodu geçersiz veya süresi dolmuş" }

panel anahtarı ile çağrıldı — uygulama anahtarı şart

• Kod tek kullanımlıktır ve atomik tüketilir; ikinci deneme 401 döner
• Ömrü SSO_CODE_TTL (varsayılan 60sn); uygulamaya ve redirect_uri’ye bağlıdır
• Dönen token mevcut sessions tablosundadır — yalnızca çağıran uygulamanın anahtarıyla doğrulanabilir, izolasyon korunur
• Rol ve izinler çağıran uygulamaya özeldir; /auth/validate her çağrıda güncel RBAC durumunu döndürür

Global oturumu iptal eder — tüm uygulamalardan çıkış

{ "message": "Oturum kapatıldı" }

İzinli dönüş adreslerini listeler

{ "redirect_uris": [ { "id": 1, "application_id": "uuid", "redirect_uri": "https://harita.bandirma.edu.tr/callback", "created_at": "…" } ], "count": 1 }

İzinli dönüş adresi ekler

{ "redirect_uri": "https://harita.bandirma.edu.tr/callback" }

• Aynı adres zaten varsa mevcut kayıt döner (idempotent)

İzinli dönüş adresini siler

{ "message": "Dönüş adresi silindi" }

Panelin kendi sistem logları (scope=system)

{
  "logs": [
    {
      "id": "uuid", "ts": "2026-07-23T10:00:00Z", "scope": "system",
      "application_id": null, "service_id": null, "level": "info",
      "source": "http", "message": "POST /api/v1/apikeys → 201",
      "metadata": { "method": "POST", "path": "/api/v1/apikeys", "status": 201, "ip": "…" }
    }
  ],
  "total": 1240, "limit": 100, "offset": 0
}

Dış uygulama/servis log gönderimi

{
  "service": "odeme-servisi",
  "level": "error",
  "source": "payment.go",
  "message": "Ödeme sağlayıcısına bağlanılamadı",
  "metadata": { "order_id": "1234" }
}

Accepted (gövdesiz)

• application_id anahtardan çıkarılır — panel anahtarı ile çağrılırsa 403

curl -X POST http://localhost:20001/api/v1/logs/ingest \
  -H "X-API-Key: <uygulama-anahtarı>" -H "Content-Type: application/json" \
  -d '{"service":"odeme-servisi","level":"error","message":"Bağlantı hatası"}'

Bir uygulamanın uygulama + servis logları

• Ortak log query parametrelerini de kabul eder (limit, offset, level, q, from, to)

Tek bir servisin logları

Uygulamanın servislerini listeler

{
  "services": [
    { "id": "uuid", "application_id": "uuid", "name": "Kimlik Doğrulama",
      "slug": "auth", "description": "", "is_system": true, "created_at": "…", "updated_at": "…" }
  ]
}

• is_system: true olan auth ve roles servisleri Atlas tarafından korunur; düzenlenemez veya silinemez
• Giriş kayıtlarında parola, token ve TC kimlik bilgisi tutulmaz

Yeni servis oluşturur

{ "name": "Ödeme Servisi", "slug": "odeme-servisi", "description": "opsiyonel" }

oluşturulan servis

aynı slug zaten var

name ve description günceller (slug değişmez)

Atlas sistem servisi düzenlenemez

Servisi siler (logları FK ON DELETE CASCADE ile silinir)

Atlas sistem servisi silinemez

İstek yapan kullanıcının (X-User-Id) uygulamaları

{ "applications": [ { "id":"uuid","name":"…","description":"…","wallpaper_url":"…","owner_id":"uuid","created_at":"…","updated_at":"…" } ], "count": 1 }

Yeni uygulama oluşturur

{ "name": "Uygulama Adı", "description": "opsiyonel", "wallpaper_url": "opsiyonel" }

• X-User-Id yoksa 401

Tek uygulama

Uygulamayı günceller

• Sahibi değilse 403

Uygulamayı siler

{ "message": "Uygulama silindi" }

• Sahibi değilse 403

Uygulamaya atanmış kullanıcılar

{ "users": [ { "application_id":"uuid","user_id":"uuid","permissions":["feedback:read"],"created_at":"…" } ], "count": 1 }

Kullanıcı ekler ve izin atar

{ "user_id": "uuid", "permissions": ["feedback:read", "error_log:read"] }

• Sahibi değilse 403

Kullanıcıyı uygulamadan çıkarır

{ "message": "Kullanıcı çıkarıldı" }

• Sahibi değilse 403

Anahtarları listeler

{ "keys": [ { "id":"uuid","application_id":"uuid","name":"…","key_prefix":"a1b2c3d4","created_at":"…","expires_at":null,"revoked_at":null } ], "count": 1 }

Yeni anahtar üretir

{ "application_id": "uuid", "name": "Servis Anahtarı", "expires_at": "2027-01-01T00:00:00Z" }

{
  "key": { "id":"uuid","name":"…","key_prefix":"a1b2c3d4" },
  "plain_key": "TAM-ANAHTAR-BUNU-SAKLAYIN",
  "message": "Anahtarı güvenli bir yerde saklayın. Bir daha gösterilmeyecek."
}

Anahtarı iptal eder

{ "message": "Anahtar iptal edildi" }

Anahtarı kalıcı siler

{ "message": "Anahtar silindi" }

İzinli origin listesi

{ "origins": [ { "id": 1, "origin": "http://localhost:20000", "created_at": "…" } ] }

Origin ekler

{ "origin": "https://uygulama.example.com" }

Origin siler

Yetkili e-posta listesi

{ "emails": [ { "id": 1, "email": "admin@ogr.bandirma.edu.tr", "note": "Bilgi İşlem", "created_at": "…" } ] }

E-posta ekler

{ "email": "kullanici@ogr.bandirma.edu.tr", "note": "opsiyonel" }

zaten var

E-postayı siler

Bağlantı listesi

{ "quick_links": [ { "id":1,"title":"…","url":"https://…","icon_url":"…","sort_order":0,"created_at":"…","updated_at":"…" } ], "count": 1 }

Yeni bağlantı ekler

{ "title": "OBS", "url": "https://obs.bandirma.edu.tr", "icon_url": "opsiyonel", "sort_order": 0 }

Bağlantıyı günceller

Bağlantıyı siler

{ "message": "Bağlantı silindi" }

Kullanıcı profilini getirir

{ "user_id":"uuid","first_name":"…","last_name":"…","phone":"…","faculty":"…","department":"…","identity_no":"…","created_at":"…","updated_at":"…" }

Profili oluşturur veya günceller (full replace)

{ "first_name":"Berke","last_name":"Ergöçün","phone":"…","faculty":"…","department":"…","identity_no":"…" }

• Tüm alanlar opsiyonel (uzunluk sınırları var)
• Full replace — gönderilmeyen alanlar boşalır. Kısmi güncelleme için PATCH /users/profile kullanın

E-posta ile fakülte, bölüm ve kurum numarasını döner

{
  "user_id": "uuid",
  "username": "…",
  "email": "berke@ogr.bandirma.edu.tr",
  "user_type": "student",
  "first_name": "Berke",
  "last_name": "Ergöçün",
  "full_name": "Berke Ergöçün",
  "phone": "05001112233",
  "faculty": "Mühendislik Fakültesi",
  "department": "Bilgisayar Mühendisliği",
  "identity_no": "202112345",
  "profile_complete": true,
  "updated_at": "2026-07-26T09:12:00Z"
}

{ "error": "email parametresi zorunludur" }

{ "error": "Kullanıcı bulunamadı" }

• user_type: student | staff | unknown — e-posta alan adından türetilir, DB'de saklanmaz. Alan adı ogr. ile başlıyorsa öğrenci, aksi halde personel
• identity_no: öğrenci numarası veya personel sicil no. ÜniAPI bunu döndürmez — elle girilir
• profile_complete: fakülte + bölüm + numara üçü de doluysa true. false ise çağıran servis eksik bilgiyi sorup PATCH ile geri yazmalıdır
• Profil henüz yoksa yine 200 döner; alanlar boş string olur
• KVKK: TC kimlik (users.uni_student_id) bu yanıta dahil edilmez — identity_no ondan tamamen ayrı bir alandır

curl -H "X-API-Key: $ATLAS_API_KEY" \
  "http://localhost:20001/api/v1/users/lookup?email=ogrenci@ogr.bandirma.edu.tr"

Fakülte/bölüm/numarayı Atlas’a geri yazar (kısmi güncelleme)

{
  "faculty": "Mühendislik Fakültesi",
  "department": "Bilgisayar Mühendisliği"
}

güncellenmiş dizin kaydı
(GET /users/lookup ile aynı format)

{ "error": "Güncellenecek en az bir alan gönderilmelidir" }

{ "error": "Kullanıcı bulunamadı" }

• Merge semantiği — yalnızca gönderilen alanlar yazılır. Sadece fakülte/bölüm yazan bir servis, başka bir servisin doldurduğu ad/telefon bilgisini ezmez
• Bir alanı boşaltmak için "" gönderin; korumak için gövdeye hiç koymayın
• Uç kullanıcı oluşturmaz — kullanıcının önce Atlas üzerinden giriş yapmış olması gerekir

curl -X PATCH -H "X-API-Key: $ATLAS_API_KEY" -H "Content-Type: application/json" \
  -d '{"faculty":"Mühendislik Fakültesi","department":"Bilgisayar Mühendisliği","identity_no":"202112345"}' \
  "http://localhost:20001/api/v1/users/profile?email=ogrenci@ogr.bandirma.edu.tr"

“Bu kullanıcı bu uygulamada ne yapabilir?” — entegrasyonun kalbi

{
  "user_id": "uuid",
  "email": "ogrenci@ogr.bandirma.edu.tr",
  "application_id": "uuid",
  "is_owner": false,
  "roles": ["staj-komisyonu"],
  "permissions": ["staj:basvuru-oku", "staj:basvuru-onayla"]
}

{ "error": "Kullanıcı bulunamadı" }

• Birden çok rolün izinleri birleştirilir (tekilleştirilmiş, sıralı)
• Süresi dolmuş (expires_at) ve geri alınmış atamalar hariç tutulur
• is_owner: true → uygulama sahibi, tüm rollerin izinlerine sahiptir
• Yetkisi yoksa boş dizilerle 200 döner (404 değil)

curl -H "X-API-Key: $ATLAS_API_KEY" \
  "http://localhost:20001/api/v1/users/access?email=ogrenci@ogr.bandirma.edu.tr&application_id=<uuid>"

Uygulamanın rol kataloğu

{ "roles": [ { "id":"uuid","key":"staj-komisyonu","name":"Staj Komisyonu","description":"…","auto_grant":false,"permissions":["staj:basvuru-oku"] } ], "count": 1 }

• Listeleme herkese açıktır — kullanıcı ne talep edebileceğini görsün diye

Yeni rol tanımlar

{
  "name": "Staj Komisyonu",
  "auto_grant": false,
  "permissions": ["staj:basvuru-oku", "staj:basvuru-onayla"]
}

aynı key zaten var

• key üretilirken Türkçe karakterler ASCII’ye indirgenir: “Staj Komisyonu” → staj-komisyonu

Rolün adını, açıklamasını ve otomatik atama ayarını günceller

{ "name": "Staj Komisyonu", "auto_grant": true }

güncel rol

• key güncellenmez; rolün sabit tanımlayıcısıdır

Rolü, atamalarını ve taleplerini siler

{ "message": "Rol silindi" }

• Rol atamaları ve talepleri FK cascade ile silinir

Rolün izin listesini tümüyle değiştirir

{ "permissions": ["staj:basvuru-oku", "staj:basvuru-onayla"] }

güncel rol

• Tek transaction — kısmi güncelleme olmaz

Kullanıcı bir rol için yetki talebi açar

{ "role_id": "uuid", "justification": "Bölüm staj komisyonu üyesiyim" }

talep (status: "pending")

// auto_grant rol ise:
// status: "approved", rol anında atanır

{ "error": "Bu rol için zaten bekleyen bir talebiniz var" }
{ "error": "Bu role zaten sahipsiniz" }

Onayımı bekleyen talepler (sahibi olduğum uygulamalar için)

{
  "requests": [ {
    "id": "uuid", "status": "pending",
    "justification": "…",
    "role_key": "staj-komisyonu", "role_name": "Staj Komisyonu",
    "application_name": "Staj Sistemi",
    "user_email": "…", "created_at": "…"
  } ],
  "count": 1
}

Kullanıcının kendi talepleri

Talebi onaylar VE rolü atar

{ "note": "Bölüm başkanlığı teyit etti" }

güncel talep (status: "approved")

uygulama sahibi değilsiniz

talep pending değil (zaten karara bağlanmış)

• Karar atomiktir — iki onaylayıcı aynı anda karar veremez, ikinci deneme 404 döner

Talebi reddeder (rol atanmaz)

Kullanıcı kendi bekleyen talebini geri çeker

{ "message": "Talep geri çekildi" }

Sahip, talep beklemeden doğrudan rol atar

{ "email": "kullanici@ogr.bandirma.edu.tr" }

{ "message": "Rol atandı" }

Kullanıcının rolünü geri alır

{ "message": "Rol geri alındı" }

• Kayıt silinmez, revoked_at işaretlenir — denetim izi korunur

Uygulama bazlı hata kaydı ekler

{ "level": "error", "message": "…", "stack_trace": "…", "metadata": {} }

• Başlık: X-App-ID: <uygulama-uuid>

Uygulama bazlı geribildirim ekler

{ "user_identifier": "opsiyonel", "message": "…", "rating": 5, "metadata": {} }

• Başlık: X-App-ID: <uygulama-uuid>
• rating 1–5 aralığında

Bir uygulamanın hata kayıtlarını listeler (panel)

Bir uygulamanın geribildirimlerini, okuma durumuyla filtreleyerek listeler (panel)

Geribildirimi okundu veya okunmadı olarak işaretler

{ "read": true }

güncel geribildirim

Tüm Atlas veritabanını düz SQL dosyası olarak indirir

Content-Type: application/sql; atlas-YYYYMMDD-HHMMSS.sql

• Yalnızca authorized_emails listesinde bulunan SSO kullanıcıları erişebilir
• Dump, mevcut veritabanına geri yüklenebilmesi için clean/if-exists SQL üretir

Doğrulanmış SQL yedeğini veritabanına geri yükler

{ "message": "SQL yedeği geri yüklendi" }

• Yıkıcı işlemdir: başarılı geri yükleme mevcut veriyi değiştirir; önce dump alın
• SQL hatasında tek transaction geri alınır

En son 200 başarılı giriş denetim kaydını döndürür

{ "logs": [{ "user_id":"uuid", "email":"…", "ip_address":"…", "created_at":"…" }], "count": 1 }

Birleşik logs tablosuna yazar (scope=application, source=errorlog-service)

{ "app_id": "uygulama-uuid", "level": "error", "message": "…", "stack_trace": "…" }

• app_id ve message zorunlu
• stack_trace, metadata.stack_trace içine konur

Ana atlas_db'deki feedbacks tablosuna yazar

{ "app_id": "uygulama-uuid", "user_identifier": "opsiyonel", "message": "…", "rating": 5 }

• app_id ve message zorunlu