Kimlik doğrulama

API sürümü 2026-10-affable-towhee

Lingara API'ye yapılan her çağrı bir erişim token'ı taşır. Bir sunucu bunu, bir OAuth istemcisinin kimliğini ve gizli anahtarını token uç noktasında değiştirerek alır: kendi adına hareket eden bir sunucu için OAuth 2.0'ın client credentials yetkilendirmesi. İstemcileri Lingara web uygulamasının Entegrasyonlar sayfasında, app.getlingara.com/admin adresinde oluşturun.

Oturum mu, istemci mi

Lingara uygulamaları sizi bir oturumla giriş yaptırır; oturum her kapsama sahiptir ve planınızın kullanım hakkını harcar. İstemci daha dardır: izin verilen kapsamlarını oluştururken siz seçersiniz ve aldığı her erişim token'ı yalnızca istediği kapsamları taşır.

Üç değer

İstemci kimliği lgr_cid_ ile başlar ve token uç noktasında istemciyi tanımlar. Gizli değildir.

İstemci gizli anahtarı lgr_cs_ ile başlar ve yalnızca token uç noktasına gönderilir. Yalnızca bir kez, oluşturduğunuzda gösterilir: o anda kopyalayın, çünkü Lingara onun yalnızca bir özetini (hash) saklar.

Erişim token'ı lgr_at_ ile başlar ve bir saat geçerlidir. /v1/ altındaki çağrıların Authorization: Bearer başlığına konur, başka hiçbir yere değil. O başlığa ait olan tek değer odur: oraya gönderilen bir istemci gizli anahtarı 401 ile reddedilir.

Erişim token'ı alın

Token uç noktasına grant_type=client_credentials içeren bir formu POST ile gönderin. İstemci kimliğini ve gizli anahtarını ya HTTP Basic kimlik doğrulamasıyla ya da client_id ve client_secret form alanları olarak gönderin, asla ikisiyle birden değil. scope, istemcinin izin verilen kapsamlarından oluşan, boşlukla ayrılmış bir listedir; istemcinin izin verilen her kapsamını almak için onu hiç göndermeyin. Aşağıdaki komut yalnızca usage:read kapsamını, yani aşağıdaki GET /v1/usage örneğinin gerektirdiği kapsamı ister.

curl -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=usage:read"

Yanıt access_token, token_type (Bearer), expires_in (3600, saniye cinsinden) ve token'ın gerçekten sahip olduğu kapsamları içeren scope alanlarını taşır. Başarısız bir değişim, /v1/ yollarının {code, error} zarfıyla değil, OAuth hata biçimi olan {error, error_description} ile yanıt verir. Yanlış ya da iptal edilmiş bir gizli anahtar veya silinmiş bir istemci 401 ve invalid_client ile reddedilir. İstemcinin isteyemeyeceği bir kapsam, değişimin tamamının 400 ve invalid_scope ile reddedilmesine yol açar; kapsam asla sessizce daraltılmaz.

Başka bir Lingara kullanıcısı adına hareket edin

Başka bir Lingara kullanıcısı adına hareket eden bir uygulama, yetkilendirme kodu akışını kullanır. Kullanıcının tarayıcısını response_type=code, client_id, kaydettiğiniz bir adresle tam olarak eşleşen bir redirect_uri, scope, state ve bir S256 code_challenge ile yetkilendirme URL'sine yönlendirin. Kullanıcı Lingara'nın onay sayfasını görür ve code, state ve iss ile redirect_uri adresinize döner. Kodu kullanmadan önce state değerinin gönderdiğiniz değer olduğunu ve iss değerinin https://api.getlingara.com olduğunu doğrulayın.

PKCE zorunludur

Her istemci PKCE kullanır, yalnızca S256 yöntemiyle. Rastgele bir code_verifier oluşturun, onun base64url ile kodlanmış SHA-256 özetini code_challenge_method=S256 ile birlikte code_challenge olarak gönderin ve doğrulayıcıyı değişim için saklayın. Yöntem içermeyen ya da plain kullanan bir istek invalid_request ile reddedilir.

Kodu değiştirin

60 saniye içinde, istemci olarak kimlik doğrulayarak token uç noktasına grant_type=authorization_code, code, aynı redirect_uri ve code_verifier ile POST isteği gönderin; genel bir istemci yalnızca client_id gönderir. Yanıta lgr_rt_ ile başlayan bir refresh_token eklenir. Kod lgr_ac_ ile başlar ve yalnızca bir kez çalışır: ikinci kullanım invalid_grant ile reddedilir ve ilk değişimin verdiği token'ları sonlandırır.

Yenileyin

Erişim token'ının süresi dolduğunda, yine istemci olarak kimlik doğrulayarak token uç noktasına grant_type=refresh_token ve refresh_token ile POST isteği gönderin. Her yenileme yeni bir yenileme token'ı döndürür: yalnızca en yenisini saklayın. Yenilemelerinizi sırayla yapın: yerine yenisi geldikten 60 saniyeden fazla sonra kullanılan eski bir yenileme token'ı çalınmış sayılır ve o kurulumun token'larını invalid_grant ile sonlandırır. 30 gün boyunca kullanılmayan bir yenileme token'ının süresi dolar. Token uç noktası istekleri adres başına sınırlar, bu yüzden yalnızca bir token'ın süresi dolduğunda yenileyin.

Yerel uygulamalar genel istemcilerdir

Bir masaüstü, mobil ya da komut satırı uygulaması bir sırrı saklayamaz, bu yüzden genel bir istemcidir: gizli anahtarı yoktur, token uç noktasına yalnızca client_id gönderir ve http://127.0.0.1/callback (herhangi bir port) gibi bir loopback yönlendirmesi ya da com.example.app:/callback gibi özel kullanımlı bir şema kaydeder. Kullanıcı onay sayfasını her seferinde görür. Bir web sayfası istemci olamaz: ne token uç noktası ne de /v1/ çapraz kaynak ön denetimine (preflight) yanıt verir.

Kullanıcı uygulamanızı kaldırdığında

Kullanıcı uygulamanızı istediği zaman Bağlı uygulamalar bölümünden ya da yüklediyse uygulamayı kaldırarak kaldırabilir; uygulamanın bir sonraki çağrısı 401 ile başarısız olur. Kullanıcı uygulamanızdan çıkış yaptığında, uygulamanın yenileme token'ını iptal uç noktasında iptal edin; bu, o kurulumun token'larını sonlandırır.

Token'ın süresi dolduğunda

Bir saat sonra /v1/, unauthorized koduyla ve invalid_token ile başlayan bir hatayla 401 yanıtı verir. Bir çağrı 401 aldığında ya da expires_in dolmadan kısa süre önce yeniden değiştirin ve çağrıyı bir kez tekrarlayın. Değişimin kendisi invalid_client veya invalid_scope ile başarısız olursa, istemci ya da gizli anahtarı silinmiş, iptal edilmiş veya daraltılmıştır: durun ve bunu Entegrasyonlar sayfasında düzeltin, çünkü yeniden denemek başarılı olamaz. Token'ı çağrılar arasında saklayın: token uç noktası değişimleri istemci ve adres başına sınırlar ve her çağrıda değişim yapan bir program bir saat içinde 429 ve rate_limited ile reddedilir (Retry-After süresini bekleyin). Bu yetkilendirmenin yenileme token'ı yoktur: gizli anahtar yeniden değiştirilir.

Erişim token'ları yalnızca API yollarına ulaşır

Erişim token'ı yalnızca /v1/ altındaki yollarda çalışır. Başka bir Lingara yoluna gönderildiğinde 401 ile reddedilir ve gövde api_token_not_accepted ile başlar; düz metin olarak ya da bir error alanının içinde, asla /v1/ yollarının kullandığı {code, error} zarfında değil. Erişim token'ını aşağıdaki gibi Authorization başlığında gönderin.

curl "https://api.getlingara.com/v1/usage" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

Kapsamlar

Her işlem, sayfasında adı verilen tam olarak bir kapsam gerektirir. Bu kapsama sahip olmayan bir erişim token'ı 403 ve insufficient_scope koduyla reddedilir. İşlemi çağırmak için, istemcinin buna izni varsa, değişim sırasında işlemin kapsamını isteyin. Aşağıdaki tablo her kapsamı ve izin verdiği işlemleri listeler.

Çağrının bedelini kim öder

Bir istemci, oluşturulurken seçilen iki yoldan biriyle ücretlendirilir. allowance istemcisi sahibinin kullanım hakkını, uygulamalarınızla aynı kullanım hakkını harcar; erişim token'ları da onu harcar. GET /v1/usage ne kadar kaldığını gösterir. metered istemcisi kullanım hakkı harcamaz: Entegrasyonlar sayfasında kurduğunuz kullanım başına ücretlendirme aboneliği üzerinden kredi başına ücretlendirilir. İstemci veya hesabınız aylık harcama sınırına ulaştığında çağrıları 402 ve spend_cap_reached ile, kullanım başına ücretlendirme etkin olmadığı sürece de 402 ve metered_billing_inactive ile reddedilir. Bir ders planı 10 kredi, bir eğitmen turu 1 kredi ve bir kelime listesi oluşturma 3 kredidir; böylece GET /v1/usage tarafından bildirilen units bu ağırlıklarla krediye çevrilir. Bir uygulamanın başka bir kullanıcı adına, yetkilendirme kodundan alınan bir token ile yaptığı çağrı, istemcinin modu ne olursa olsun her zaman o kullanıcının kullanım hakkını harcar.

Gizli anahtarları ve token'ları bir sunucuda tutun

İstemci gizli anahtarı, kontrol ettiğiniz bir sunucuda durmalıdır; herkesin okuyabileceği bir web sayfasında, tarayıcı eklentisinde ya da uygulama paketinde asla. Yerel bir uygulama genel bir istemcidir ve gizli anahtar tutmaz. Ne /v1/ ne de token uç noktası çapraz kaynak ön denetimine (preflight) yanıt verir, dolayısıyla başka bir sitedeki tarayıcı onları zaten çağıramaz.

İstemcileri yönetin

Entegrasyonlar sayfasında, app.getlingara.com/admin adresinde istemcileri oluşturun, yeniden adlandırın ve silin, her birinin neler yapabileceğini ve hangi sürüme sabitlendiğini değiştirin, gizli anahtarlarını oluşturun ve iptal edin. Bir istemciyi silmek, sahip olduğu her erişim token'ını anında durdurur ve her kullanıcının ona verdiği izni sona erdirir. Bir gizli anahtarı iptal etmek, o gizli anahtarla değiştirilerek alınmış her erişim token'ını anında durdurur. Bir istemcinin kapsamlarını daraltmak da anında uygulanır; genişletmek ya da sürümünü değiştirmek bir sonraki değişimden itibaren uygulanır.

Gizli anahtarı yenileyin

Bir istemcinin aynı anda iki gizli anahtarı olabilir. Yenilemek için yeni bir gizli anahtar oluşturun, onu dağıtın ve eskisinin Entegrasyonlar sayfasındaki Son kullanım tarihi değişmeyi bıraktığında eskisini iptal edin. Yeni gizli anahtara zaten sahip olan ama hâlâ eskisinden alınmış bir token tutan bir süreç bir kez 401 alır ve yeniden değiştirir. Bir istemcinin tek gizli anahtarı iptal edilemez: önce yerine geçecek olanı oluşturun ya da istemciyi silin.

Bir çeviri ile İngilizce referans arasında fark varsa, İngilizce referans geçerlidir.