Autentikasi

Versi API 2026-10-affable-towhee

Setiap panggilan ke API Lingara membawa token akses. Server mendapatkannya dengan menukar ID dan rahasia klien OAuth di endpoint token: pemberian kredensial klien (client credentials grant) OAuth 2.0, untuk server yang bertindak atas nama dirinya sendiri. Buat klien di halaman Integrasi pada aplikasi web Lingara, di app.getlingara.com/admin.

Sesi atau klien

Aplikasi Lingara memasukkan Anda dengan sesi, yang memiliki semua cakupan dan menggunakan kuota paket Anda. Klien lebih sempit: Anda memilih cakupan yang diizinkan untuknya saat membuatnya, dan setiap token akses yang diperolehnya hanya membawa cakupan yang dimintanya.

Tiga nilai

ID klien diawali lgr_cid_ dan menyebutkan klien di endpoint token. ID klien bukan rahasia.

Rahasia klien diawali lgr_cs_ dan hanya dikirim ke endpoint token. Rahasia hanya ditampilkan sekali, saat Anda membuatnya: salin saat itu juga, karena Lingara hanya menyimpan hash-nya.

Token akses diawali lgr_at_ dan berlaku satu jam. Token ini dimasukkan ke header Authorization: Bearer pada panggilan di bawah /v1/, dan tidak di tempat lain. Hanya token akses yang boleh berada di header tersebut: rahasia klien yang dikirim ke sana ditolak dengan 401.

Dapatkan token akses

Kirim formulir dengan POST ke endpoint token dengan grant_type=client_credentials. Kirim ID klien dan rahasia dengan autentikasi HTTP Basic atau sebagai kolom formulir client_id dan client_secret, jangan keduanya. scope adalah daftar cakupan yang diizinkan untuk klien, dipisahkan spasi; hilangkan untuk mendapatkan semua cakupan yang diizinkan untuk klien. Perintah di bawah hanya meminta usage:read, cakupan yang dibutuhkan contoh GET /v1/usage di bagian 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 berisi access_token, token_type (Bearer), expires_in (3600, dalam detik) dan scope, yaitu cakupan yang benar-benar dimiliki token. Penukaran yang gagal dijawab dalam bentuk galat OAuth, {error, error_description}, bukan amplop {code, error} milik /v1/. Rahasia yang salah atau dicabut, atau klien yang dihapus, ditolak dengan 401 dan invalid_client. Cakupan yang tidak boleh diminta klien menolak seluruh penukaran dengan 400 dan invalid_scope; cakupan tidak pernah dipersempit diam-diam.

Bertindak untuk pengguna Lingara lain

Aplikasi yang bertindak untuk pengguna Lingara lain menggunakan pemberian kode otorisasi (authorization code grant). Arahkan peramban pengguna ke URL otorisasi dengan response_type=code, client_id, redirect_uri yang sama persis dengan salah satu yang Anda daftarkan, scope, state, dan code_challenge dengan metode S256. Pengguna melihat halaman persetujuan Lingara dan kembali ke redirect_uri Anda dengan code, state, dan iss. Pastikan state adalah yang Anda kirim dan iss adalah https://api.getlingara.com sebelum Anda menggunakan kode itu.

PKCE wajib

Setiap klien menggunakan PKCE, hanya dengan metode S256. Buat code_verifier acak, kirim hash SHA-256-nya, dalam enkode base64url, sebagai code_challenge dengan code_challenge_method=S256, dan simpan verifier itu untuk penukaran. Permintaan tanpa metode, atau dengan plain, ditolak dengan invalid_request.

Tukarkan kode

Dalam 60 detik, kirim POST ke endpoint token dengan grant_type=authorization_code, code, redirect_uri yang sama, dan code_verifier, dengan mengautentikasi sebagai klien; klien publik hanya mengirim client_id. Respons menambahkan refresh_token, yang diawali lgr_rt_. Kode diawali lgr_ac_ dan hanya berfungsi sekali: penggunaan kedua ditolak dengan invalid_grant dan mengakhiri token yang diterbitkan oleh penukaran pertama.

Penyegaran

Saat token akses kedaluwarsa, kirim POST ke endpoint token dengan grant_type=refresh_token dan refresh_token, dengan mengautentikasi sebagai klien lagi. Setiap penyegaran mengembalikan token penyegaran baru: simpan hanya yang terbaru. Lakukan penyegaran satu per satu: token penyegaran lama yang digunakan lebih dari 60 detik setelah diganti dianggap dicuri, dan mengakhiri token instalasi itu dengan invalid_grant. Token penyegaran yang tidak digunakan selama 30 hari akan kedaluwarsa. Endpoint token membatasi permintaan per alamat, jadi lakukan penyegaran hanya saat token habis masa berlakunya.

Aplikasi native adalah klien publik

Aplikasi desktop, seluler, atau baris perintah tidak dapat menyimpan rahasia, jadi aplikasi itu adalah klien publik: tidak memiliki rahasia, hanya mengirim client_id ke endpoint token, dan mendaftarkan pengalihan loopback seperti http://127.0.0.1/callback (port apa pun) atau skema penggunaan pribadi seperti com.example.app:/callback. Pengguna melihat halaman persetujuan setiap kali. Halaman web tidak dapat menjadi klien: baik endpoint token maupun /v1/ tidak menjawab preflight lintas asal.

Saat pengguna menghapus aplikasi Anda

Pengguna dapat menghapus aplikasi Anda kapan saja di Aplikasi terhubung, atau dengan mencopot pemasangannya jika merekalah yang memasangnya, dan panggilan berikutnya dari aplikasi itu gagal dengan 401. Saat pengguna keluar dari aplikasi Anda, cabut token penyegarannya di endpoint pencabutan, yang mengakhiri token instalasi itu.

Saat token kedaluwarsa

Setelah satu jam, /v1/ menjawab 401 dengan kode unauthorized dan galat yang diawali invalid_token. Tukar ulang saat sebuah panggilan mendapat 401, atau sesaat sebelum expires_in habis, lalu coba ulang panggilan itu sekali. Jika penukaran itu sendiri gagal dengan invalid_client atau invalid_scope, klien atau rahasianya telah dihapus, dicabut, atau dipersempit: berhenti dan perbaiki di halaman Integrasi, karena mencoba ulang tidak mungkin berhasil. Simpan token di antara panggilan: endpoint token membatasi penukaran per klien dan per alamat, dan program yang menukar di setiap panggilan ditolak dengan 429 dan rate_limited dalam satu jam (tunggu sesuai Retry-After). Pemberian ini tidak memiliki token penyegaran: rahasia ditukar ulang.

Token akses hanya menjangkau rute API

Token akses hanya berfungsi pada rute di bawah /v1/. Jika dikirim ke rute Lingara lainnya, token ditolak dengan 401, dan isi respons diawali api_token_not_accepted, sebagai teks biasa atau di dalam kolom error, tidak pernah dalam amplop {code, error} yang digunakan rute /v1/. Kirim token akses di header Authorization, seperti di bawah.

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

Cakupan

Setiap operasi memerlukan tepat satu cakupan, yang disebutkan di halamannya. Token akses tanpa cakupan tersebut ditolak dengan 403 dan kode insufficient_scope. Untuk memanggil operasi itu, minta cakupannya saat penukaran, jika klien diizinkan. Tabel di bawah mencantumkan setiap cakupan dan operasi yang diizinkannya.

Siapa yang membayar panggilan

Klien ditagih dengan salah satu dari dua cara, yang dipilih saat klien dibuat. Klien allowance menggunakan kuota pemiliknya, kuota yang sama dengan aplikasi Anda, dan token aksesnya juga menggunakannya; GET /v1/usage menampilkan sisanya. Klien metered tidak menggunakan kuota: klien ini ditagih per kredit melalui langganan penagihan per pemakaian yang Anda siapkan di halaman Integrasi. Panggilannya ditolak dengan 402 dan spend_cap_reached begitu klien atau akun Anda mencapai batas pengeluaran bulanannya, dan dengan 402 dan metered_billing_inactive selama penagihan per pemakaian tidak aktif. Satu rencana pelajaran bernilai 10 kredit, satu giliran tutor 1 kredit, dan satu pembuatan kosakata 3 kredit, sehingga units yang dilaporkan GET /v1/usage dapat dikonversi ke kredit dengan bobot tersebut. Panggilan yang dilakukan aplikasi untuk pengguna lain, dengan token dari kode otorisasi, selalu menggunakan kuota pengguna itu, apa pun mode kliennya.

Simpan rahasia dan token di server

Rahasia klien seharusnya berada di server yang Anda kendalikan, jangan pernah di halaman web, ekstensi peramban, atau bundel aplikasi, tempat siapa pun dapat membacanya. Aplikasi native adalah klien publik dan tidak memegang rahasia. Baik /v1/ maupun endpoint token tidak menjawab preflight lintas asal, sehingga peramban di situs lain memang tidak dapat memanggilnya.

Kelola klien

Di halaman Integrasi, di app.getlingara.com/admin, buat, ganti nama, dan hapus klien, ubah apa yang dapat dilakukan setiap klien dan versi yang disematkan padanya, serta buat dan cabut rahasianya. Menghapus klien langsung menghentikan semua token akses yang dimilikinya, dan mengakhiri izin yang telah diberikan setiap pengguna kepadanya. Mencabut rahasia langsung menghentikan semua token akses yang ditukar dengan rahasia itu. Mempersempit cakupan klien juga langsung berlaku; memperluasnya, atau mengubah versinya, berlaku mulai penukaran berikutnya.

Rotasi rahasia

Satu klien dapat memiliki dua rahasia sekaligus. Untuk merotasi, buat rahasia baru, terapkan, lalu cabut rahasia lama setelah tanggal Terakhir digunakan miliknya di halaman Integrasi berhenti berubah. Proses yang sudah memiliki rahasia baru tetapi masih memegang token dari rahasia lama akan mendapat satu 401 lalu menukar ulang. Satu-satunya rahasia klien tidak dapat dicabut: buat penggantinya terlebih dahulu, atau hapus klien.

Jika terjemahan berbeda dengan referensi berbahasa Inggris, referensi berbahasa Inggris yang berlaku.