Cara membuat klien OAuth

Versi API 2026-10-affable-towhee

Sebelum Anda menekan Buat klien di halaman Integrasi, tentukan tiga hal: apa yang boleh dilakukan klien, proses mana yang memegang rahasianya, dan siapa yang membayar panggilannya. Panduan Autentikasi menyatakan aturannya; halaman ini menerapkannya pada dua perusahaan fiktif, Luba dan Farducks.

Luba: Dive Deck

Luba mengoperasikan kapal selam otonom sebagai layanan transportasi dan tumpangan bersama. Dive Deck menampilkan kepada setiap penumpang satu frasa dari penyelaman itu di layar kabin, dalam bahasa yang sedang mereka pelajari, dan tim operasional Luba memantau berapa banyak kuota yang tersisa.

Luba membuat satu klien, Luba Dive Deck, yang diizinkan untuk Buat kosakata (vocab:generate) dan Baca penggunaan (usage:read), ditagihkan ke Jatah paket Anda (allowance). Dua proses berbagi klien ini, dan masing-masing hanya meminta cakupan yang dibutuhkannya saat penukaran. Penukaran yang menghilangkan scope mendapatkan semua cakupan yang diizinkan untuk klien; penukaran yang meminta cakupan yang tidak diizinkan untuk klien ditolak seluruhnya dengan invalid_scope, tidak pernah dipersempit diam-diam.

Server pengiriman menulis frasa untuk setiap penyelaman. Server ini hanya meminta vocab:generate, sehingga token yang bocor darinya tidak dapat 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}'

Dasbor operasional adalah proses sisi server kedua dengan ID klien dan rahasia yang sama. Dasbor ini hanya meminta usage:read, dan membaca sisa 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 proses berjalan di server Luba. Tablet di kabin meminta frasa dari server pengiriman dan tidak pernah memegang rahasia atau token, karena apa pun di perangkat yang dapat disentuh penumpang dapat dibaca. Bagian “Simpan rahasia dan token di server” dalam panduan Autentikasi menjelaskan alasannya.

Klien yang sama sebagai proyek yang dapat Anda klon dan jalankan: integrations/luba-dive-deck

Farducks: Batter Rewards

Farducks adalah jaringan toko swalayan ikan dan kentang goreng. Selagi pesanan digoreng, aplikasi loyalitas Batter Rewards meminta rencana pelajaran singkat dari backend milik Farducks sendiri, lalu membacanya kembali. Aplikasi dan mesin kasir memanggil backend Farducks, tidak pernah Lingara, sehingga keduanya tidak memegang rahasia.

Farducks membuat satu klien, Farducks Batter Rewards, yang diizinkan untuk Buat rencana pelajaran (lesson_plans:write) dan Baca rencana pelajaran (lesson_plans:read), ditagihkan ke Jatah paket Anda (allowance). Saat ini hanya itu penagihan yang dapat dipakai untuk membuat klien, dan penagihan klien ditetapkan saat klien dibuat. Mode lainnya, metered (Bayar sesuai pemakaian), dijelaskan di bagian “Siapa yang membayar panggilan” dalam panduan Autentikasi.

Backend hanya meminta lesson_plans:write dan membuat rencana. Respons dialirkan, dan peristiwa started-nya membawa plan_id rencana tersebut.

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}'

Setel ID ke plan_id tersebut, lalu minta lesson_plans:read dan baca kembali rencananya. Satu penukaran dapat meminta beberapa cakupan klien, dipisahkan spasi dalam scope; setiap perintah di sini hanya meminta satu, karena masing-masing disusun dari satu panggilan saja.

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"

Suatu hari, rahasia itu tertempel di sebuah tiket dukungan. Di halaman Integrasi, Farducks menekan Rahasia baru dan menerapkannya ke backend, menunggu sampai tanggal Terakhir digunakan milik rahasia lama berhenti berubah, lalu menekan Cabut pada rahasia lama. Sejak saat itu, semua token akses yang ditukar dengan rahasia lama ditolak. Bagian “Rotasi rahasia” dalam panduan Autentikasi menjelaskan batas dua rahasia dan alasan satu-satunya rahasia klien tidak dapat dicabut.

Klien yang sama sebagai proyek yang dapat Anda klon dan jalankan: integrations/farducks-batter-rewards

Langkah selanjutnya

Panduan Autentikasi membahas galat penukaran, apa yang harus dilakukan saat token kedaluwarsa, dan aturan rotasi. Panduan Versi membahas versi yang disematkan pada klien, dan cara memilih versi lain untuk satu panggilan.

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