Chuyển tới nội dung chính

OAuth cho ứng dụng đối tác

Ứng dụng đối tác, công cụ tự động hóa hoặc ứng dụng tùy chỉnh làm việc cho một người dùng MonoChat có thể gọi API hàm tùy chỉnh (POST https://app.monochat.ai/api/<slug>/custom-functions/<path>) bằng mã truy cập OAuth thay vì API token. Người dùng chấp thuận ứng dụng trên một trang MonoChat, chọn các tổ chức mà ứng dụng được truy cập và có thể thu hồi bất cứ lúc nào trong Ứng dụng đã kết nối ở cài đặt hồ sơ.

API token vẫn hoạt động trên cùng endpoint. OAuth là lựa chọn cho ứng dụng hành động thay người khác: ứng dụng không bao giờ thấy mật khẩu hay API token, và mỗi người dùng có thể tự ngắt kết nối.

Ứng dụng hành động với tư cách người dùng

Lệnh gọi bằng mã truy cập chạy với tư cách người dùng đã chấp thuận ứng dụng, với vai trò của người đó. Lệnh gọi chỉ chạy các phương thức tùy chỉnh của tổ chức, và chỉ trong các tổ chức mà người dùng là nhân viên.

Nhận một client​

Hãy đề nghị MonoChat cấp một client cho ứng dụng của bạn. MonoChat đăng ký client với:

  • tên ứng dụng, hiển thị trên trang chấp thuận và trong Ứng dụng đã kết nối;
  • các URI chuyển hướng, khớp chính xác: địa chỉ https, hoặc http trên localhost, 127.0.0.1 hay [::1] (cổng bất kỳ);
  • các phạm vi ứng dụng được yêu cầu: custom-functions:run cho API này.

Bạn nhận được client ID (bắt đầu bằng monochat_rc_) và client secret (bắt đầu bằng monochat_cs_). Secret chỉ hiển thị một lần; MonoChat chỉ lưu mã băm của nó. Hãy giữ secret trên máy chủ của bạn, không bao giờ trong trình duyệt hay ứng dụng di động.

Ứng dụng không giữ được secret, chẳng hạn ứng dụng chạy trong trình duyệt hoặc trên máy tính của người dùng, có thể dùng URL của một tài liệu metadata client làm client ID, như các client MCP. Khi đó ứng dụng không gửi secret.

Endpoint​

Metadata của máy chủ ủy quyền tại https://app.monochat.ai/.well-known/oauth-authorization-server liệt kê mọi endpoint. Trên bản cài đặt white-label hoặc tự lưu trữ, hãy dùng địa chỉ riêng của bản cài đặt đó.

Cài đặtGiá trị
Endpoint ủy quyềnhttps://app.monochat.ai/oauth/authorize
Endpoint tokenhttps://app.monochat.ai/oauth/token
Endpoint thu hồihttps://app.monochat.ai/oauth/revoke
Tài nguyênhttps://app.monochat.ai/api/custom-functions
Phạm vicustom-functions:run
Xác thực clientHTTP Basic, hoặc client_id và client_secret trong nội dung yêu cầu

Metadata riêng của tài nguyên nằm tại https://app.monochat.ai/.well-known/oauth-protected-resource/api/custom-functions.

Kết nối một người dùng​

MonoChat dùng luồng mã ủy quyền với PKCE (S256). Người dùng cần đã thiết lập xác minh hai bước (qua email hoặc ứng dụng xác thực).

  1. Chuyển người dùng tới endpoint ủy quyền với response_type=code, client_id của bạn, một redirect_uri đã đăng ký, scope=custom-functions:run, resource=https://app.monochat.ai/api/custom-functions, một state và một code_challenge với code_challenge_method=S256.
  2. Người dùng đăng nhập MonoChat nếu cần. Trang chấp thuận hiển thị tên ứng dụng của bạn và Chạy các phương thức tùy chỉnh thay cho bạn. Người dùng có thể chọn Tổ chức mà ứng dụng được truy cập (tất cả của họ nếu không chọn), nhập mã xác nhận 6 chữ số và nhấp Cho phép.
  3. MonoChat đưa người dùng trở lại redirect_uri của bạn với code, state và iss. Nếu người dùng nhấp Từ chối, MonoChat gửi error=access_denied thay vào đó.
  4. Đổi mã tại endpoint token trong vòng 5 phút:
curl -X POST https://app.monochat.ai/oauth/token \
-u "<client_id>:<client_secret>" \
-d grant_type=authorization_code \
-d code=<code> \
-d redirect_uri=<redirect_uri> \
-d code_verifier=<code_verifier>

Phản hồi gồm một access_token (bắt đầu bằng monochat_at_) có hiệu lực expires_in giây (một giờ), một refresh_token (bắt đầu bằng monochat_rt_) và scope được cấp.

Gọi API​

Gửi mã truy cập dưới dạng bearer token:

curl -X POST https://app.monochat.ai/api/<slug>/custom-functions/<path> \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{}'
Trạng tháiKhi nào
401Token không xác định, đã hết hạn hoặc bị thu hồi, hoặc được cấp cho tài nguyên khác, chẳng hạn máy chủ MCP. Header WWW-Authenticate trỏ tới metadata của tài nguyên.
403Tổ chức không nằm trong số người dùng cho phép ứng dụng, người dùng không có quyền truy cập tổ chức, hoặc quyền được cấp không có custom-functions:run.
429Đã chạm giới hạn; hãy chờ số giây trong Retry-After. Lệnh gọi được đếm theo phút: 120 cho mỗi quyền được cấp và 1.200 cho mỗi client, ngoài giới hạn riêng của tổ chức cho endpoint này.

Làm mới và thu hồi​

  • Làm mới: trước khi mã truy cập hết hạn, gọi endpoint token với grant_type=refresh_token và refresh_token. Mỗi lần làm mới trả về một refresh token mới; hãy dùng token mới. Refresh token được dùng lại sau hơn một phút kể từ khi bị thay thế sẽ chấm dứt quyền được cấp.
  • Hết hạn: quyền được cấp kết thúc 90 ngày sau lần làm mới cuối, khi người dùng thu hồi trong Ứng dụng đã kết nối, hoặc khi người dùng đổi hay đặt lại mật khẩu. Khi đó người dùng phải chấp thuận ứng dụng lại.
  • Thu hồi: để ngắt kết nối một người dùng, gửi mã truy cập hoặc refresh token tới endpoint thu hồi kèm xác thực client của bạn:
curl -X POST https://app.monochat.ai/oauth/revoke \
-u "<client_id>:<client_secret>" \
-d token=<refresh_token>

Kết nối lại cùng một người dùng với ứng dụng của bạn sẽ thay thế quyền được cấp trước đó.