Cách tạo ứng dụng khách OAuth

Phiên bản API 2026-10-affable-towhee

Trước khi nhấn Tạo ứng dụng khách trên trang Tích hợp, hãy quyết định ba điều: ứng dụng khách được làm gì, tiến trình nào giữ khóa bí mật của nó, và ai trả tiền cho các lệnh gọi của nó. Hướng dẫn Xác thực nêu các quy tắc; trang này áp dụng chúng cho hai công ty hư cấu, Luba và Farducks.

Luba: Dive Deck

Luba vận hành tàu ngầm tự hành làm dịch vụ vận tải và đi chung. Dive Deck của Luba hiển thị cho mỗi hành khách một cụm từ của chuyến lặn trên màn hình trong khoang, bằng ngôn ngữ họ đang học, và đội vận hành của Luba theo dõi hạn mức còn lại bao nhiêu.

Luba tạo một ứng dụng khách, Luba Dive Deck, được phép Tạo từ vựng (vocab:generate) và Đọc mức sử dụng (usage:read), tính phí vào Hạn mức trong gói của bạn (allowance). Hai tiến trình dùng chung ứng dụng khách này, và mỗi tiến trình chỉ yêu cầu phạm vi mình cần khi đổi. Lần đổi bỏ trống scope sẽ nhận mọi phạm vi mà ứng dụng khách được phép; lần đổi yêu cầu một phạm vi mà ứng dụng khách không được phép sẽ bị từ chối toàn bộ với invalid_scope, không bao giờ bị thu hẹp một cách âm thầm.

Máy chủ điều phối viết các cụm từ cho mỗi chuyến lặn. Nó chỉ yêu cầu vocab:generate, nên một token bị lộ từ máy chủ này không thể đọc mức sử dụng của 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}'

Bảng điều khiển vận hành là tiến trình phía máy chủ thứ hai, dùng cùng ID ứng dụng khách và khóa bí mật. Nó chỉ yêu cầu usage:read, và đọc phần hạn mức còn lại.

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"

Cả hai tiến trình đều chạy trên máy chủ của Luba. Máy tính bảng trong khoang xin cụm từ từ máy chủ điều phối và không bao giờ giữ khóa bí mật hay token, vì mọi thứ trên thiết bị mà hành khách có thể chạm vào đều có thể bị đọc. Mục “Giữ khóa bí mật và token trên máy chủ” trong hướng dẫn Xác thực giải thích lý do.

Cùng client đó dưới dạng dự án bạn có thể clone và chạy: integrations/luba-dive-deck

Farducks: Batter Rewards

Farducks là chuỗi cửa hàng tiện lợi bán cá và khoai tây chiên. Trong lúc món đang chiên, ứng dụng khách hàng thân thiết Batter Rewards xin backend riêng của Farducks một giáo án ngắn, rồi đọc lại giáo án đó. Ứng dụng và máy tính tiền gọi backend của Farducks, không bao giờ gọi Lingara, nên không bên nào giữ khóa bí mật.

Farducks tạo một ứng dụng khách, Farducks Batter Rewards, được phép Tạo kế hoạch bài học (lesson_plans:write) và Đọc kế hoạch bài học (lesson_plans:read), tính phí vào Hạn mức trong gói của bạn (allowance). Hiện đây là cách tính phí duy nhất có thể chọn khi tạo ứng dụng khách, và cách tính phí của một ứng dụng khách được cố định khi tạo. Chế độ còn lại, metered (Trả theo mức dùng), được mô tả trong mục “Ai trả tiền cho một lệnh gọi” của hướng dẫn Xác thực.

Backend chỉ yêu cầu lesson_plans:write và tạo giáo án. Phản hồi được truyền phát, và sự kiện started của nó mang plan_id của giáo án.

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

Đặt ID thành plan_id đó, rồi yêu cầu lesson_plans:read và đọc lại giáo án. Một lần đổi có thể yêu cầu nhiều phạm vi của ứng dụng khách, phân cách bằng dấu cách trong scope; mỗi lệnh ở đây chỉ yêu cầu một phạm vi, vì mỗi lệnh được ghép từ một lệnh gọi duy nhất.

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"

Một ngày nọ, khóa bí mật bị dán vào một phiếu hỗ trợ. Trên trang Tích hợp, Farducks nhấn Khóa bí mật mới và triển khai khóa đó lên backend, chờ đến khi ngày Dùng lần cuối của khóa cũ không còn thay đổi, rồi nhấn Thu hồi trên khóa cũ. Kể từ lúc đó, mọi token truy cập đã được đổi bằng khóa cũ đều bị từ chối. Mục “Xoay vòng khóa bí mật” trong hướng dẫn Xác thực nêu giới hạn hai khóa bí mật và lý do không thể thu hồi khóa bí mật duy nhất của một ứng dụng khách.

Cùng client đó dưới dạng dự án bạn có thể clone và chạy: integrations/farducks-batter-rewards

Đọc tiếp

Hướng dẫn Xác thực trình bày các lỗi của lần đổi, việc cần làm khi token hết hạn, và quy tắc xoay vòng. Hướng dẫn Phiên bản trình bày phiên bản mà ứng dụng khách được ghim, và cách chọn phiên bản khác cho một lệnh gọi.

Nếu bản dịch và tài liệu tham chiếu tiếng Anh khác nhau, tài liệu tham chiếu tiếng Anh là bản đúng.