Xác thực

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

Mỗi lệnh gọi đến API Lingara đều mang theo một token truy cập. Máy chủ lấy token truy cập bằng cách đổi ID và khóa bí mật của một ứng dụng khách OAuth tại điểm cuối token: đó là luồng cấp quyền client credentials của OAuth 2.0, dành cho máy chủ hoạt động với tư cách chính nó. Hãy tạo ứng dụng khách trên trang Tích hợp của ứng dụng web Lingara, tại app.getlingara.com/admin.

Phiên đăng nhập hay ứng dụng khách

Các ứng dụng Lingara đăng nhập cho bạn bằng một phiên; phiên có mọi phạm vi và tiêu hạn mức của gói bạn dùng. Ứng dụng khách thì hẹp hơn: bạn chọn các phạm vi được phép cho nó khi tạo, và mỗi token truy cập nó nhận được chỉ mang những phạm vi mà nó yêu cầu.

Ba giá trị

ID ứng dụng khách bắt đầu bằng lgr_cid_ và xác định ứng dụng khách tại điểm cuối token. Đây không phải là thông tin bí mật.

Khóa bí mật của ứng dụng khách bắt đầu bằng lgr_cs_ và chỉ được gửi đến điểm cuối token. Khóa chỉ hiển thị một lần, khi bạn tạo nó: hãy sao chép ngay lúc đó, vì Lingara chỉ lưu bản băm của khóa.

Token truy cập bắt đầu bằng lgr_at_ và có hiệu lực một giờ. Token được đặt trong header Authorization: Bearer của các lệnh gọi thuộc /v1/, và không ở đâu khác. Đó là giá trị duy nhất được đặt trong header này: khóa bí mật của ứng dụng khách gửi vào đó sẽ bị từ chối với 401.

Lấy token truy cập

Gửi POST một biểu mẫu đến điểm cuối token với grant_type=client_credentials. Gửi ID ứng dụng khách và khóa bí mật bằng xác thực HTTP Basic hoặc bằng các trường biểu mẫu client_id và client_secret, không bao giờ dùng cả hai. scope là danh sách các phạm vi được phép của ứng dụng khách, phân cách bằng dấu cách; bỏ trống nó để nhận mọi phạm vi mà ứng dụng khách được phép. Lệnh bên dưới chỉ yêu cầu usage:read, phạm vi mà ví dụ GET /v1/usage ở phần sau cần.

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"

Phản hồi chứa access_token, token_type (Bearer), expires_in (3600, tính bằng giây) và scope, tức các phạm vi mà token thực sự có. Một lần đổi thất bại trả lời theo dạng lỗi của OAuth, {error, error_description}, chứ không phải phong bì {code, error} của /v1/. Khóa bí mật sai hoặc đã bị thu hồi, hay ứng dụng khách đã bị xóa, sẽ bị từ chối với 401 và invalid_client. Một phạm vi mà ứng dụng khách không được yêu cầu sẽ khiến toàn bộ lần đổi bị từ chối với 400 và invalid_scope; phạm vi không bao giờ bị thu hẹp một cách âm thầm.

Hành động thay cho người dùng Lingara khác

Ứng dụng hành động thay cho người dùng Lingara khác dùng luồng cấp quyền bằng mã ủy quyền. Hãy chuyển trình duyệt của người dùng đến URL ủy quyền với response_type=code, client_id, một redirect_uri khớp chính xác với một URI bạn đã đăng ký, scope, state và một code_challenge S256. Người dùng sẽ thấy trang đồng ý của Lingara và quay lại redirect_uri của bạn với code, state và iss. Hãy kiểm tra rằng state đúng là giá trị bạn đã gửi và iss là https://api.getlingara.com trước khi dùng mã.

Bắt buộc dùng PKCE

Mọi ứng dụng khách đều dùng PKCE, chỉ với phương thức S256. Hãy tạo một code_verifier ngẫu nhiên, gửi giá trị băm SHA-256 của nó, mã hóa base64url, làm code_challenge cùng với code_challenge_method=S256, và giữ lại verifier cho lần đổi. Yêu cầu không có phương thức, hoặc dùng plain, sẽ bị từ chối với invalid_request.

Đổi mã

Trong vòng 60 giây, gửi POST đến điểm cuối token với grant_type=authorization_code, code, cùng redirect_uri đó và code_verifier, xác thực với tư cách ứng dụng khách; ứng dụng khách công khai chỉ gửi client_id. Phản hồi có thêm refresh_token, bắt đầu bằng lgr_rt_. Mã bắt đầu bằng lgr_ac_ và chỉ dùng được một lần: lần dùng thứ hai bị từ chối với invalid_grant và chấm dứt các token mà lần đổi đầu tiên đã cấp.

Làm mới

Khi token truy cập hết hạn, gửi POST đến điểm cuối token với grant_type=refresh_token và refresh_token, lại xác thực với tư cách ứng dụng khách. Mỗi lần làm mới trả về một token làm mới mới: chỉ giữ token mới nhất. Hãy thực hiện các lần làm mới tuần tự: một token làm mới cũ được dùng hơn 60 giây sau khi đã bị thay thế sẽ bị coi là bị đánh cắp, và chấm dứt các token của bản cài đặt đó với invalid_grant. Token làm mới không được dùng trong 30 ngày sẽ hết hạn. Điểm cuối token giới hạn số yêu cầu cho mỗi địa chỉ, nên chỉ làm mới khi token đã hết hạn.

Ứng dụng gốc là ứng dụng khách công khai

Ứng dụng máy tính, di động hoặc dòng lệnh không thể giữ bí mật, nên nó là ứng dụng khách công khai: nó không có khóa bí mật, chỉ gửi client_id đến điểm cuối token, và đăng ký một chuyển hướng loopback như http://127.0.0.1/callback (cổng bất kỳ) hoặc một scheme dùng riêng như com.example.app:/callback. Người dùng thấy trang đồng ý mỗi lần. Một trang web không thể là ứng dụng khách: cả điểm cuối token lẫn /v1/ đều không trả lời yêu cầu preflight khác nguồn gốc.

Khi người dùng gỡ ứng dụng của bạn

Người dùng có thể gỡ ứng dụng của bạn bất cứ lúc nào trong Ứng dụng đã kết nối, hoặc bằng cách gỡ cài đặt nếu họ đã cài nó, và lệnh gọi tiếp theo của ứng dụng sẽ thất bại với 401. Khi người dùng đăng xuất khỏi ứng dụng của bạn, hãy thu hồi token làm mới của nó tại điểm cuối thu hồi, việc này chấm dứt các token của bản cài đặt đó.

Khi token hết hạn

Sau một giờ, /v1/ trả lời 401 với mã unauthorized và một lỗi bắt đầu bằng invalid_token. Hãy đổi lại khi một lệnh gọi nhận 401, hoặc ngay trước khi expires_in hết, rồi thử lại lệnh gọi một lần. Nếu chính lần đổi thất bại với invalid_client hoặc invalid_scope, thì ứng dụng khách hoặc khóa bí mật của nó đã bị xóa, thu hồi hoặc thu hẹp: hãy dừng lại và sửa trên trang Tích hợp, vì thử lại không thể thành công. Hãy giữ token giữa các lệnh gọi: điểm cuối token giới hạn số lần đổi cho mỗi ứng dụng khách và mỗi địa chỉ, và chương trình đổi ở mỗi lệnh gọi sẽ bị từ chối với 429 và rate_limited trong vòng một giờ (hãy chờ theo Retry-After). Luồng cấp quyền này không có token làm mới: khóa bí mật được đổi lại.

Token truy cập chỉ dùng được với các tuyến API

Token truy cập chỉ hoạt động trên các tuyến thuộc /v1/. Nếu gửi đến bất kỳ tuyến Lingara nào khác, token bị từ chối với 401, và phần thân bắt đầu bằng api_token_not_accepted, ở dạng văn bản thuần hoặc bên trong trường error, không bao giờ nằm trong phong bì {code, error} mà các tuyến /v1/ dùng. Hãy gửi token truy cập trong header Authorization, như bên dưới.

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

Phạm vi

Mỗi thao tác cần đúng một phạm vi, được ghi trên trang của thao tác đó. Token truy cập không có phạm vi đó bị từ chối với 403 và mã insufficient_scope. Để gọi thao tác đó, hãy yêu cầu phạm vi của nó khi đổi, nếu ứng dụng khách được phép. Bảng dưới đây liệt kê từng phạm vi và các thao tác mà phạm vi đó cho phép.

Ai trả tiền cho một lệnh gọi

Một ứng dụng khách được tính phí theo một trong hai cách, được chọn khi tạo nó. Ứng dụng khách allowance tiêu hạn mức của chủ sở hữu, cùng hạn mức với các ứng dụng của bạn, và các token truy cập của nó cũng vậy; GET /v1/usage cho biết phần còn lại. Ứng dụng khách metered không tiêu hạn mức: nó được tính phí theo tín dụng qua một gói đăng ký tính phí theo mức dùng mà bạn thiết lập trên trang Tích hợp. Các lệnh gọi của nó bị từ chối với 402 và spend_cap_reached khi ứng dụng khách hoặc tài khoản của bạn chạm hạn mức chi tiêu hằng tháng, và với 402 và metered_billing_inactive khi tính phí theo mức dùng chưa được kích hoạt. Một giáo án là 10 tín dụng, một lượt với gia sư là 1 tín dụng và một lần tạo từ vựng là 3 tín dụng, nên units mà GET /v1/usage báo cáo được quy đổi ra tín dụng theo các trọng số đó. Lệnh gọi mà một ứng dụng thực hiện thay cho người dùng khác, bằng token lấy từ mã ủy quyền, luôn tiêu hạn mức của người dùng đó, bất kể chế độ của ứng dụng khách.

Giữ khóa bí mật và token trên máy chủ

Khóa bí mật của ứng dụng khách phải nằm trên máy chủ do bạn kiểm soát, không bao giờ nằm trong trang web, tiện ích mở rộng trình duyệt hay gói ứng dụng, nơi bất kỳ ai cũng đọc được. Ứng dụng gốc là ứng dụng khách công khai và không giữ khóa bí mật nào. Cả /v1/ lẫn điểm cuối token đều không trả lời yêu cầu preflight khác nguồn gốc, nên dù sao trình duyệt ở trang khác cũng không thể gọi chúng.

Quản lý ứng dụng khách

Trên trang Tích hợp, tại app.getlingara.com/admin, bạn có thể tạo, đổi tên và xóa ứng dụng khách, thay đổi những gì mỗi ứng dụng khách được làm và phiên bản mà nó được ghim, cũng như tạo và thu hồi khóa bí mật của nó. Xóa một ứng dụng khách sẽ dừng ngay mọi token truy cập mà nó đang giữ, và chấm dứt quyền mà mọi người dùng đã cấp cho nó. Thu hồi một khóa bí mật sẽ dừng ngay mọi token truy cập đã được đổi bằng khóa đó. Thu hẹp phạm vi của ứng dụng khách cũng có hiệu lực ngay; mở rộng phạm vi, hoặc đổi phiên bản, có hiệu lực từ lần đổi tiếp theo.

Xoay vòng khóa bí mật

Một ứng dụng khách có thể giữ hai khóa bí mật cùng lúc. Để xoay vòng, hãy tạo khóa bí mật mới, triển khai nó, rồi thu hồi khóa cũ khi ngày Dùng lần cuối của khóa cũ trên trang Tích hợp không còn thay đổi. Một tiến trình đã có khóa bí mật mới nhưng vẫn giữ token từ khóa cũ sẽ nhận một lần 401 rồi đổi lại. Không thể thu hồi khóa bí mật duy nhất của một ứng dụng khách: hãy tạo khóa thay thế trước, hoặc xóa ứng dụng khách.

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.