Kimlik doğrulama ve kapsam

Entegrasyon anahtarının kapsamını belirleyin; dış API ile uygulama oturumunu ayırın.

Son güncelleme: 2026-11-10

Bu sayfada

Önce entegrasyon kimliğini seçin Anahtarı saklayın ve yenileyin Uygulama oturumunun yeri Tarayıcı oturumu açma Tarayıcı istemcisi CSRF ve entegrasyon sınırı Oturum uçları Yetki kontrolü

Önce entegrasyon kimliğini seçin

Dış entegrasyon için kullanıcıya bağlı erişim anahtarı kullanın. v1 uçları Authorization: Bearer ERISIM_ANAHTARI başlığını bekler; bu uçlarda oturum çerezi kabul edilmez. Anahtarı kullanıcı menüsündeki Erişim anahtarları bölümünden oluşturabilirsiniz. İlk çağrı için Hızlı başlangıç sayfasını izleyin.

Anahtar kapsamı	Proje kapsamı	Kullanım
`oku`	Seçili projeler	Yetkili projelerde nesne, cihaz, devre ve değişiklik okuma.
`oku`, `yaz`	Seçili projeler	Güncel proje rolü, bölge, modül ve lisans izinleriyle okuma ve düzenleme.
Her iki kapsam seçeneği	`proje_ids: null`	Kullanıcının erişebildiği projelerle sınırlı genel kapsam.
Her iki kapsam seçeneği	`proje_ids: []`	Hiçbir projeye erişim vermez.

Anahtarın sahibi pasifleşirse, kurum erişimi kapanırsa, süre dolarsa veya anahtar iptal edilirse aynı sırla devam etmeyin. Anahtar sahibi hesabın güncel izinleri her istekte uygulanır. İzleyici hesabı yazma kapsamı alamaz.

Anahtarı saklayın ve yenileyin

Sır yalnız oluşturma yanıtında gösterilir. Güvenli sunucu yapılandırmasında saklayın; URL, kaynak kodu, tarayıcı paketi ve günlük içine koymayın. Kapsamı değiştirmek veya sırrı yenilemek için yeni anahtar oluşturun, entegrasyonun yeni anahtarla çalıştığını kontrol edin ve eski anahtarı İptal et ile kaldırın.

Sır açığa çıktıysa ilgili anahtarı iptal edin ve yeni sır üretin; aynı sırrı farklı adla kullanmayın. Anahtarın erişebildiği projeleri ve kurumunuzdaki ilgili kayıtları inceleyin. Erişim anahtarları yönetim uçlarını ve yaşam döngüsünü açıklar.

Uygulama oturumunun yeri

Aşağıdaki çerezli uçlar tarayıcı uygulamasının oturum sözleşmesidir. Anahtar oluşturma ve webhook yönetimi bu oturumu gerektirir. Dış okuma/yazma entegrasyonunda v1 yerine bütün uygulama uçlarının anahtar kabul edeceğini varsaymayın.

Tarayıcı oturumu açma

POST /api/auth/login, JSON gövdesinde username ve password alanlarını alır. username alanında kullanıcı adı veya kayıtlı e-posta kullanılabilir. Başarılı yanıt aşağıdaki biçimdedir:

{"ok": true}

Sunucu, sosogis_oturum adlı çerezi oluşturur. Çerez HttpOnly, Secure, SameSite=Lax ve Path=/ niteliklerine sahiptir. Oturum açılışından itibaren süre 30 gündür; her istekte yeniden uzatılmaz. Secure nedeniyle bağlantı HTTPS üzerinden sunulmalıdır. Sonraki istekler aynı oturum çerezini taşır; yanıt gövdesinden bearer token alınmaz.

Hatalı giriş 401 döndürür. İstek sınırı aşıldığında 429 yanıtını ve varsa Retry-After başlığını değerlendirin. Kullanıcı veya kurum etkin değilse oturum kullanılamaz.

Tarayıcı istemcisi

Uygulama kendi API çağrılarını aynı kaynak üzerinde yapar. Mevcut oturumla kullanıcı bilgisini okumak için:

const yanit = await fetch('/api/auth/me', {
  credentials: 'same-origin',
  cache: 'no-store'
});
if (!yanit.ok) throw new Error(`HTTP ${yanit.status}`);
const kullanici = await yanit.json();

JSON yazma isteklerinde Content-Type: application/json kullanılmalıdır. Dosya yüklerken FormData oluşturulur; Content-Type başlığını tarayıcının sınır bilgisiyle birlikte üretmesine izin verilir.

CSRF ve entegrasyon sınırı

Mevcut uygulama API’sinde ayrı bir CSRF belirteci üretme veya X-CSRF-Token başlığı doğrulama akışı yoktur. Oturum çerezinin SameSite=Lax niteliği ve aynı kaynak üzerinden çağrı yapan istemci kullanılır. Bu durum, farklı kaynaklardan doğrudan tarayıcı entegrasyonunun hazır olduğu anlamına gelmez; genel CORS yapılandırması tanımlı değildir.

Dış entegrasyon için kullanıcılar erişim anahtarı oluşturabilir. Anahtar /api/v1 ve OGC uçlarında kullanılır; bu sayfadaki çerezli uygulama uçlarının oturum gereksinimini kaldırmaz. Merkezi yönetimin servis kimliği, kullanıcıya bağlı erişim anahtarından ayrıdır.

Oturum uçları

Yöntem ve uç	İşlev
`GET /api/auth/me`	Kullanıcı, `role`, `role_name`, `can_edit`, `is_admin` ve `lisans` bilgisi
`GET /api/auth/check`	Geçerli oturumda gövdesiz `204` yanıtı
`POST /api/auth/logout`	Oturumu siler ve çerezi kaldırır
`POST /api/auth/password`	`current` ve `new` alanlarıyla parola değiştirir

Yeni parola 8–200 karakter olmalıdır. Parola değişince diğer oturumlar kapatılır; işlemi yapan oturum korunur. Kimlik bilgilerini uygulama kaynak koduna veya entegrasyon günlüklerine koymayın.

Yetki kontrolü

Roller superadmin, admin, editor ve viewer değerleridir. API’de viewer rolünün Türkçe adı İzleyici olarak döner. Yazma yetkisi tek başına yeterli değildir; ilgili modül, kurum, proje üyeliği, bölge yetkisi ve lisans koşulları da sağlanmalıdır.

Kurum dışındaki bir proje, var olsa da 404 ile yanıtlanır. Oturum kaybı 401, yetki veya lisans nedeniyle yazma reddi 403 olabilir. Ayrıntılar için Hata kodları sayfasına bakın.