Nuvaka › Geliştirici belgeleri › Nuvaka ile giriş

Nuvaka ile giriş

Masaüstü programın, web siten ya da komut satırı aracın kullanıcıyı Nuvaka hesabıyla tanıyabilir. Kullanıcı izin verirse uygulaman ona bildirim gönderebilir ve seçtiği tek bir Dosyalarım klasöründe okuyup yazabilir. Standart OAuth 2.1 ve OpenID Connect; hazır kütüphanelerle çalışır.

Nasıl çalışır#

• Parola hiç girilmez. Kullanıcı ne tarayıcıda ne de senin uygulamanda Nuvaka parolası yazar. Onay, kullanıcının zaten oturum açık olduğu Nuvaka General App'te verilir.
• Tarayıcıdaki onay sayfası kısa bir onay kodu (XXXX-XXXX) ve "General App'te onayla" düğmesi (nuvaka://oauth?code=…) gösterir. Uygulama açılır, kullanıcı uygulamanın adını, dönüş adresini ve istenen izinleri görür; onaylar ya da reddeder. Kod elle de girilebilir: Profil › Bağlı uygulamalar.
• Kullanıcı bağlı uygulamalarını aynı yerde görür ve Erişimi kaldır ile istediği an iptal eder; tüm token'lar anında geçersiz olur. Her girişte kullanıcıya "X uygulamasına giriş yapıldı" bildirimi gider.

İstemci kaydı#

İstemcileri şimdilik Nuvaka ekibi kaydeder: destek üzerinden uygulamanın adını, logosunu, istemci türünü, dönüş adreslerini ve istediğin izinleri yaz. Sana bir client_id verilir (sunucu tarafı uygulamada ayrıca bir kez gösterilen nvcs_… sırrı).

Dönüş adresi (redirect_uri) kayıtla birebir eşleşmelidir. Kabul edilen biçimler: https://…; loopback http://127.0.0.1:port/… (port da kayıtlı); ters alan adlı özel şema (com.ornek.app:/cb).

İzinler (scope)#

Yalnız istemcine izinli scope'ları isteyebilirsin; bilinmeyen ya da izinsiz scope invalid_scope döner. Kullanıcı openid dışındaki izinleri kapatabilir; token yanıtındaki scope alanı gerçekte verilenleri söyler.

Uç noktalar#

Issuer: https://generalappapi.nuvaka.com. Keşif belgesi tüm adresleri verir; kütüphanene yalnız bunu göster.

Hatalar RFC 6749 biçimindedir: { error, error_description }; kötü istemci 401 invalid_client. Uçlar IP başına dakikada 60 istekle sınırlıdır (429).

Yetkilendirme kodu + PKCE (masaüstü ve web)#

PKCE zorunludur ve yalnız S256 kabul edilir. state (CSRF) ve nonce önerilir.

1. PKCE üret

   code_verifier 43–128 karakter rastgele; code_challenge = BASE64URL(SHA256(code_verifier)).

2. Tarayıcıyı aç

   Kullanıcıyı onay sayfasına gönder. Masaüstünde loopback dinleyici (http://127.0.0.1:PORT/cb) ya da özel şema kullan.

3. Kullanıcı General App'te onaylar

   Sayfa kendini 2 saniyede bir yoklar. Onayda redirect_uri?code=nvac_…&state=…&iss=…, reddedilirse redirect_uri?error=access_denied&state=…&iss=… adresine döner. state'i ve iss'i doğrula.

4. Kodu takas et

   Kod tek kullanımlık ve 5 dakikalık; aynı redirect_uri gönderilmeli. İstek (onay sayfası) 10 dakika geçerlidir.

# 2) Tarayıcıda açılacak adres
https://generalappapi.nuvaka.com/oauth/authorize?response_type=code
  &client_id=ornek-masaustu
  &redirect_uri=http%3A%2F%2F127.0.0.1%3A53682%2Fcb
  &scope=openid%20profile%20storage.folder%20offline_access
  &state=RASTGELE&nonce=RASTGELE
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256

# 4) Kod takası
curl -X POST https://generalappapi.nuvaka.com/oauth/token \
  -d grant_type=authorization_code -d code=nvac_… \
  -d redirect_uri=http://127.0.0.1:53682/cb \
  -d code_verifier=… -d client_id=ornek-masaustu

{ "access_token": "nvo_…", "token_type": "Bearer", "expires_in": 3600,
  "scope": "openid profile storage.folder offline_access",
  "refresh_token": "nvr_…", "id_token": "eyJ…" }

Yönlendirilen hatalar (dönüş adresi doğrulandıktan sonra): unsupported_response_type, invalid_request (PKCE yok ya da S256 değil), invalid_scope. Bilinmeyen istemci ya da kayıtsız dönüş adresinde yönlendirme yapılmaz, hata sayfası gösterilir.

Cihaz akışı (TV, konsol, komut satırı)#

Tarayıcısı olmayan ya da dönüş adresi alamayan araçlar için (RFC 8628).

curl -X POST https://generalappapi.nuvaka.com/oauth/device -d client_id=ornek-cli -d scope="openid profile"
# → { device_code, user_code: "WDJB-MJHT", verification_uri, verification_uri_complete, expires_in: 600, interval: 5 }

# Kullanıcıya user_code'u ve verification_uri'yi göster (ya da verification_uri_complete için QR).
# Sonra interval saniyede bir yokla:
curl -X POST https://generalappapi.nuvaka.com/oauth/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:device_code -d device_code=… -d client_id=ornek-cli

Yoklama yanıtları: authorization_pending (bekle), slow_down (aralığı artır), access_denied, expired_token ya da başarıda token'lar.

Token'lar#

• Yenileme döner: grant_type=refresh_token her kullanımda yeni bir erişim ve yeni bir yenileme token'ı verir; eskisi hemen iptal olur. İptal edilmiş bir yenileme token'ı yeniden gelirse (sızıntı belirtisi) bağlantının bütün token'ları iptal edilir ve invalid_grant döner. Yeni token'ı hemen sakla.
• id_token: iss, aud (= client_id), sub, iat, exp, varsa nonce; profile ile preferred_username, email ile email ve email_verified. İmzayı /oauth/jwks ile doğrula.
• Token'lar opaktır; içeriklerine güvenme, erişim reddedilirse yenile ya da yeniden giriş iste.

Uygulama API'si#

Taban adres https://generalappapi.nuvaka.com/api/oauth-api/, başlık Authorization: Bearer nvo_….

Hatalar: geçersiz ya da süresi dolmuş token 401 invalid_token; izin yok 403 insufficient_scope; seçilen klasörün dışı 403 out_of_scope. Hesap silinir ya da engellenirse, istemci kapatılırsa veya kullanıcı erişimi kaldırırsa token anında geçersiz olur.

Güvenlik önerileri#

• state'i her istekte rastgele üret ve dönüşte karşılaştır; iss parametresini (RFC 9207) doğrula.
• Yalnız gerçekten kullandığın izinleri iste; email kapatılmış olabilir.
• Token'ları işletim sisteminin anahtar deposunda sakla; günlüğe yazma.
• Kullanıcıya onay kodunu uygulamanda da göster; Nuvaka onay ekranında "Bu isteği sen başlatmadıysan onaylama" uyarısı bulunur.

Nuvaka Apps API v1 · son güncelleme 2026-09-28