Pengesahan

Versi API 2026-10-affable-towhee

Setiap panggilan kepada API Lingara membawa token akses. Pelayan mendapatkannya dengan menukar ID dan rahsia klien OAuth di titik akhir token: pemberian kelayakan klien (client credentials grant) OAuth 2.0, untuk pelayan yang bertindak sebagai dirinya sendiri. Cipta klien pada halaman Integrasi dalam aplikasi web Lingara, di app.getlingara.com/admin.

Sesi atau klien

Aplikasi Lingara mendaftar masuk anda dengan sesi, yang memegang setiap skop dan menggunakan kuota pelan anda. Klien lebih sempit: anda memilih skop yang dibenarkan untuknya semasa menciptanya, dan setiap token akses yang diperolehnya hanya membawa skop yang dimintanya.

Tiga nilai

ID klien bermula dengan lgr_cid_ dan menamakan klien di titik akhir token. Ia bukan rahsia.

Rahsia klien bermula dengan lgr_cs_ dan hanya dihantar ke titik akhir token. Ia ditunjukkan sekali sahaja, semasa anda menciptanya: salin ketika itu, kerana Lingara hanya menyimpan cincangannya.

Token akses bermula dengan lgr_at_ dan sah selama satu jam. Ia diletakkan dalam pengepala Authorization: Bearer bagi panggilan di bawah /v1/, dan tidak di tempat lain. Ia satu-satunya nilai yang layak berada dalam pengepala itu: rahsia klien yang dihantar ke situ ditolak dengan 401.

Dapatkan token akses

POST borang ke titik akhir token dengan grant_type=client_credentials. Hantar ID klien dan rahsia sama ada dengan pengesahan HTTP Basic atau sebagai medan borang client_id dan client_secret, tidak sekali-kali kedua-duanya. scope ialah senarai skop yang dibenarkan untuk klien, dipisahkan dengan ruang; tinggalkannya untuk mendapatkan setiap skop yang dibenarkan untuk klien. Arahan di bawah hanya meminta usage:read, skop yang diperlukan oleh contoh GET /v1/usage di bawah.

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"

Respons membawa access_token, token_type (Bearer), expires_in (3600, dalam saat) dan scope, iaitu skop yang benar-benar dipegang oleh token. Pertukaran yang gagal menjawab dalam bentuk ralat OAuth, {error, error_description}, bukan sampul {code, error} bagi /v1/. Rahsia yang salah atau dibatalkan, atau klien yang dipadam, ditolak dengan 401 dan invalid_client. Skop yang tidak boleh diminta oleh klien menolak seluruh pertukaran dengan 400 dan invalid_scope; ia tidak sekali-kali disempitkan secara senyap.

Bertindak bagi pihak pengguna Lingara lain

Aplikasi yang bertindak bagi pihak pengguna Lingara lain menggunakan pemberian kod kebenaran (authorization code grant). Hantar pelayar pengguna ke URL kebenaran dengan response_type=code, client_id, redirect_uri yang sepadan tepat dengan salah satu yang anda daftarkan, scope, state dan code_challenge dengan kaedah S256. Pengguna melihat halaman persetujuan Lingara dan kembali ke redirect_uri anda dengan code, state dan iss. Pastikan state ialah yang anda hantar dan iss ialah https://api.getlingara.com sebelum anda menggunakan kod itu.

PKCE diwajibkan

Setiap klien menggunakan PKCE, dengan kaedah S256 sahaja. Jana code_verifier rawak, hantar cincangan SHA-256nya, dikodkan dalam base64url, sebagai code_challenge dengan code_challenge_method=S256, dan simpan verifier itu untuk pertukaran. Permintaan tanpa kaedah, atau dengan plain, ditolak dengan invalid_request.

Tukar kod

Dalam masa 60 saat, POST ke titik akhir token dengan grant_type=authorization_code, code, redirect_uri yang sama dan code_verifier, dengan mengesahkan sebagai klien; klien awam hanya menghantar client_id. Respons menambah refresh_token, yang bermula dengan lgr_rt_. Kod bermula dengan lgr_ac_ dan berfungsi sekali sahaja: penggunaan kedua ditolak dengan invalid_grant dan menamatkan token yang dikeluarkan oleh pertukaran pertama.

Muat semula

Apabila token akses tamat tempoh, POST ke titik akhir token dengan grant_type=refresh_token dan refresh_token, dengan mengesahkan sebagai klien sekali lagi. Setiap muat semula mengembalikan token muat semula yang baharu: simpan yang terbaharu sahaja. Lakukan muat semula satu demi satu: token muat semula lama yang digunakan lebih daripada 60 saat selepas ia diganti dianggap dicuri, dan menamatkan token pemasangan itu dengan invalid_grant. Token muat semula yang tidak digunakan selama 30 hari akan tamat tempoh. Titik akhir token mengehadkan permintaan bagi setiap alamat, jadi muat semula hanya apabila token tamat tempoh.

Aplikasi asli ialah klien awam

Aplikasi desktop, mudah alih atau baris perintah tidak dapat menyimpan rahsia, jadi ia ialah klien awam: ia tiada rahsia, hanya menghantar client_id ke titik akhir token, dan mendaftarkan ubah hala loopback seperti http://127.0.0.1/callback (sebarang port) atau skema kegunaan peribadi seperti com.example.app:/callback. Pengguna melihat halaman persetujuan setiap kali. Halaman web tidak boleh menjadi klien: baik titik akhir token mahupun /v1/ tidak menjawab preflight rentas asal.

Apabila pengguna mengalih keluar aplikasi anda

Pengguna boleh mengalih keluar aplikasi anda pada bila-bila masa dalam Aplikasi bersambung, atau dengan menyahpasangnya jika merekalah yang memasangnya, dan panggilan seterusnya daripada aplikasi itu gagal dengan 401. Apabila pengguna log keluar daripada aplikasi anda, batalkan token muat semulanya di titik akhir pembatalan, yang menamatkan token pemasangan itu.

Apabila token tamat tempoh

Selepas satu jam, /v1/ menjawab 401 dengan kod unauthorized dan ralat yang bermula dengan invalid_token. Tukar semula apabila sesuatu panggilan mendapat 401, atau sejurus sebelum expires_in habis, dan cuba semula panggilan itu sekali. Jika pertukaran itu sendiri gagal dengan invalid_client atau invalid_scope, klien atau rahsianya telah dipadam, dibatalkan atau disempitkan: berhenti dan betulkannya pada halaman Integrasi, kerana mencuba semula tidak akan berjaya. Simpan token antara panggilan: titik akhir token mengehadkan pertukaran bagi setiap klien dan setiap alamat, dan program yang menukar pada setiap panggilan ditolak dengan 429 dan rate_limited dalam tempoh sejam (tunggu Retry-After). Pemberian ini tiada token muat semula: rahsia ditukar semula.

Token akses hanya mencapai laluan API

Token akses hanya berfungsi pada laluan di bawah /v1/. Jika dihantar ke laluan Lingara lain, ia ditolak dengan 401, dan kandungan bermula dengan api_token_not_accepted, sebagai teks biasa atau dalam medan error, tidak sekali-kali dalam sampul {code, error} yang digunakan oleh laluan /v1/. Hantar token akses dalam pengepala Authorization, seperti di bawah.

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

Skop

Setiap operasi memerlukan tepat satu skop, yang dinamakan pada halamannya. Token akses tanpa skop itu ditolak dengan 403 dan kod insufficient_scope. Untuk memanggil operasi itu, minta skopnya semasa pertukaran, jika klien dibenarkan. Jadual di bawah menyenaraikan setiap skop dan operasi yang dibenarkannya.

Siapa yang membayar sesuatu panggilan

Klien dibilkan dengan salah satu daripada dua cara, yang dipilih semasa ia dicipta. Klien allowance menggunakan kuota pemiliknya, kuota yang sama dengan aplikasi anda, dan token aksesnya juga menggunakannya; GET /v1/usage menunjukkan bakinya. Klien metered tidak menggunakan kuota: ia dibilkan mengikut kredit melalui langganan pengebilan bermeter yang anda sediakan di halaman Integrasi. Panggilannya ditolak dengan 402 dan spend_cap_reached sebaik sahaja klien atau akaun anda mencapai had perbelanjaan bulanannya, dan dengan 402 dan metered_billing_inactive selagi pengebilan bermeter tidak aktif. Satu rancangan pelajaran bernilai 10 kredit, satu giliran tutor 1 kredit dan satu penjanaan kosa kata 3 kredit, jadi units yang dilaporkan oleh GET /v1/usage boleh ditukar kepada kredit dengan pemberat tersebut. Panggilan yang dibuat oleh aplikasi bagi pihak pengguna lain, dengan token daripada kod kebenaran, sentiasa menggunakan kuota pengguna itu, tanpa mengira mod klien.

Simpan rahsia dan token pada pelayan

Rahsia klien sepatutnya berada pada pelayan yang anda kawal, tidak sekali-kali dalam halaman web, sambungan pelayar atau berkas aplikasi, di mana sesiapa sahaja boleh membacanya. Aplikasi asli ialah klien awam dan tidak memegang rahsia. Baik /v1/ mahupun titik akhir token tidak menjawab preflight rentas asal, jadi pelayar di laman lain memang tidak dapat memanggilnya.

Urus klien

Pada halaman Integrasi, di app.getlingara.com/admin, cipta, namakan semula dan padam klien, ubah apa yang boleh dilakukan oleh setiap klien dan versi yang disematkan padanya, serta cipta dan batalkan rahsianya. Memadam klien menghentikan setiap token akses yang dipegangnya serta-merta, dan menamatkan kebenaran yang diberikan oleh setiap pengguna kepadanya. Membatalkan rahsia menghentikan, serta-merta, setiap token akses yang ditukar dengan rahsia itu. Menyempitkan skop klien juga berkuat kuasa serta-merta; meluaskannya, atau menukar versinya, berkuat kuasa mulai pertukaran seterusnya.

Putarkan rahsia

Klien boleh memegang dua rahsia pada masa yang sama. Untuk memutarkan, cipta rahsia baharu, gunakan ia, dan batalkan rahsia lama sebaik sahaja tarikh Kali terakhir digunakan pada halaman Integrasi berhenti berubah. Proses yang sudah mempunyai rahsia baharu tetapi masih memegang token daripada rahsia lama akan mendapat satu 401 dan menukar semula. Satu-satunya rahsia klien tidak boleh dibatalkan: cipta penggantinya dahulu, atau padam klien itu.

Jika terjemahan dan rujukan bahasa Inggeris berbeza, rujukan bahasa Inggeris adalah yang betul.