OAuth 2.1

Cho ứng dụng khác đăng nhập người dùng bằng tài khoản Bot-Hosting, giống Đăng nhập bằng Discord. Xây dựng trên OAuth 2.1 và PKCE, nên client OAuth chuẩn nào cũng dùng được.

Dùng khóa API để điều khiển tài khoản của chính bạn. Dùng OAuth khi bạn xây dựng ứng dụng thao tác trên tài khoản của người khác, để họ đăng nhập và đồng ý thay vì dán khóa. Các trợ lý AI như ChatGPT kết nối đúng theo luồng này.

Luồng hoạt động

01 Tạo ứng dụng Đăng ký tên và redirect URI trong cài đặt nhà phát triển. Bạn nhận được client_id công khai, không có secret.
02 Chuyển người dùng đến để cấp quyền Chuyển hướng đến /oauth/authorize kèm PKCE. Người dùng đăng nhập và chấp thuận các phạm vi quyền.
03 Đổi mã lấy token Họ quay lại kèm một code. POST code đó đến endpoint token để nhận access token.
04 Gọi API thay mặt họ Gửi token dưới dạng Bearer đến /api/v1, và làm mới nó ở chế độ nền.

Endpoint

Endpoint	Mục đích
GET /oauth/authorize	Màn hình đồng ý của người dùng, mở trong trình duyệt.
POST /api/oauth/token	Đổi code lấy token, hoặc làm mới token.
POST /api/oauth/register	Dynamic Client Registration (RFC 7591), không bắt buộc.
GET /.well-known/oauth-authorization-server	Siêu dữ liệu khám phá.
GET /.well-known/oauth-protected-resource	Siêu dữ liệu tài nguyên, do các client MCP sử dụng.

Thời hạn của token

Mã ủy quyền 10 phút Dùng một lần, gắn với PKCE.

Access token 7 ngày Bearer cho các lệnh gọi /api/v1.

Refresh token 30 ngày Được xoay vòng sau mỗi lần dùng.

Làm mới

Mỗi lần làm mới đều trả về một refresh token mới và thu hồi token cũ: luôn ghi đè token đã lưu. Nếu việc làm mới trả về invalid_grant, hãy đưa người dùng quay lại bước 1.

Bảo mật

Lưu token phía máy chủ, gắn với người dùng của bạn. Không bao giờ gửi chúng xuống trình duyệt hoặc đưa vào kho mã nguồn công khai.
Token bị thu hồi ngay khi người dùng ngắt kết nối ứng dụng của bạn.
Dùng redirect URI https trong môi trường production. http được chấp nhận để thử nghiệm cục bộ.
Token OAuth không bao giờ cấp quyền admin, dù phạm vi quyền nào được chấp thuận.