Cara mencipta klien OAuth

Versi API 2026-10-affable-towhee

Sebelum anda menekan Cipta klien pada halaman Integrasi, tentukan tiga perkara: apa yang boleh dilakukan oleh klien, proses mana yang memegang rahsianya, dan siapa yang membayar panggilannya. Panduan Pengesahan menyatakan peraturannya; halaman ini menerapkannya pada dua syarikat rekaan, Luba dan Farducks.

Luba: Dive Deck

Luba mengendalikan kapal selam autonomi sebagai perkhidmatan pengangkutan dan perkongsian tunggangan. Dive Deck memaparkan kepada setiap penumpang satu frasa bagi selaman itu pada skrin kabin, dalam bahasa yang sedang dipelajarinya, dan pasukan operasi Luba memantau berapa banyak kuota yang masih tinggal.

Luba mencipta satu klien, Luba Dive Deck, yang dibenarkan untuk Jana kosa kata (vocab:generate) dan Baca penggunaan (usage:read), dibilkan kepada Peruntukan pelan anda (allowance). Dua proses berkongsi klien ini, dan setiap satu hanya meminta skop yang diperlukannya semasa pertukaran. Pertukaran yang meninggalkan scope mendapat setiap skop yang dibenarkan untuk klien; pertukaran yang meminta skop yang tidak dibenarkan untuk klien ditolak sepenuhnya dengan invalid_scope, tidak sekali-kali disempitkan secara senyap.

Pelayan penghantaran menulis frasa bagi setiap selaman. Ia hanya meminta vocab:generate, jadi token yang bocor daripadanya tidak boleh membaca penggunaan Luba.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=vocab:generate" | jq -r '.access_token // error(.error)')"

curl -N -X POST "https://api.getlingara.com/v1/vocab/stream" \
  -H "Authorization: Bearer $LINGARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"level":2,"source_lang":"en","target_lang":"zh","count":8}'

Papan pemuka operasi ialah proses sisi pelayan kedua dengan ID klien dan rahsia yang sama. Ia hanya meminta usage:read, dan membaca baki kuota.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -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" | jq -r '.access_token // error(.error)')"

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

Kedua-dua proses berjalan pada pelayan Luba. Tablet di dalam kabin meminta frasa daripada pelayan penghantaran dan tidak sekali-kali memegang rahsia atau token, kerana apa-apa sahaja pada peranti yang boleh disentuh penumpang boleh dibaca. Bahagian “Simpan rahsia dan token pada pelayan” dalam panduan Pengesahan menerangkan sebabnya.

Klien yang sama sebagai projek yang boleh anda klon dan jalankan: integrations/luba-dive-deck

Farducks: Batter Rewards

Farducks ialah rangkaian kedai serbaneka ikan dan kentang goreng. Sementara pesanan sedang digoreng, aplikasi kesetiaan Batter Rewards meminta rancangan pelajaran pendek daripada backend Farducks sendiri, kemudian membacanya semula. Aplikasi dan mesin daftar tunai memanggil backend Farducks, tidak sekali-kali Lingara, jadi kedua-duanya tidak memegang rahsia.

Farducks mencipta satu klien, Farducks Batter Rewards, yang dibenarkan untuk Cipta pelan pelajaran (lesson_plans:write) dan Baca pelan pelajaran (lesson_plans:read), dibilkan kepada Peruntukan pelan anda (allowance). Itulah satu-satunya pengebilan yang boleh digunakan untuk mencipta klien pada masa ini, dan pengebilan klien ditetapkan semasa ia dicipta. Mod yang satu lagi, metered (Bayar ikut penggunaan), diterangkan di bawah “Siapa yang membayar sesuatu panggilan” dalam panduan Pengesahan.

Backend hanya meminta lesson_plans:write dan mencipta rancangan itu. Respons distrim, dan peristiwa started membawa plan_id rancangan itu.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=lesson_plans:write" | jq -r '.access_token // error(.error)')"

curl -N -X POST "https://api.getlingara.com/v1/lesson-plans" \
  -H "Authorization: Bearer $LINGARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"context":"Ordering food at a night market","source_lang":"en","target_lang":"zh","level":2}'

Tetapkan ID kepada plan_id itu, kemudian minta lesson_plans:read dan baca semula rancangan itu. Satu pertukaran boleh meminta beberapa skop klien, dipisahkan dengan ruang dalam scope; setiap arahan di sini hanya meminta satu, kerana setiap satu disusun daripada satu panggilan sahaja.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=lesson_plans:read" | jq -r '.access_token // error(.error)')"

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

Pada suatu hari, rahsia itu ditampal ke dalam tiket sokongan. Pada halaman Integrasi, Farducks menekan Rahsia baharu dan menggunakannya pada backend, menunggu sehingga tarikh Kali terakhir digunakan bagi rahsia lama berhenti berubah, kemudian menekan Batalkan pada rahsia lama. Mulai saat itu, setiap token akses yang ditukar dengan rahsia lama ditolak. “Putarkan rahsia”, dalam panduan Pengesahan, menerangkan had dua rahsia dan sebab satu-satunya rahsia klien tidak boleh dibatalkan.

Klien yang sama sebagai projek yang boleh anda klon dan jalankan: integrations/farducks-batter-rewards

Ke mana seterusnya

Panduan Pengesahan merangkumi ralat pertukaran, apa yang perlu dilakukan apabila token tamat tempoh, dan peraturan putaran. Panduan Versi merangkumi versi yang disematkan pada klien, dan cara memilih versi lain untuk satu panggilan.

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