CHUỘT API / INTEGRATION GUIDE

Tích hợp xác thực
không cần tự xây lại.

Tài liệu này mô tả toàn bộ flow mà website test đang sử dụng: website của bạn tạo OAuth request, Chuột API xử lý đăng nhập hoặc tạo tài khoản, sau đó trả authorization code về callback của project. Client secret chỉ chạy ở backend.

1. Kiến trúc tổng quan

Chuột API là identity provider trung tâm. Website tích hợp không tạo user trực tiếp trong database riêng cho flow này.

Website của bạn
  -> GET /api/v1/oauth/authorize
  -> Chuột API /login?client_id=...
  -> Chuột API /signup?client_id=...
  -> callback URL của project với code + state
  -> backend website đổi code tại /api/v1/oauth/token
  -> tạo session riêng cho website của bạn
  -> redirect tới direct_url của project

client_id xác định project/app, không xác định user. User được chọn hoặc tạo trên trang login/signup của Chuột API.

2. Base URL và endpoint

https://apiauth.pages.dev/api/v1

Method	Endpoint	Vai trò
GET	/oauth/authorize	Bắt đầu OAuth và chuyển user tới login/signup.
POST	/oauth/token	Backend đổi authorization code thành access token.
GET	/userinfo	Lấy thông tin user bằng access token.
POST	/auth/register	Tạo tài khoản trực tiếp trên Chuột API.
POST	/auth/login	Đăng nhập username/password.
POST	/auth/logout	Xóa session Auth API.
GET	/health	Kiểm tra trạng thái service.

3. Tạo project và credentials

Đăng nhập dashboard Chuột API.
Bấm Tạo project.
Nhập tên project.
Nhập direct_url và redirect_uri.
Lưu client_id, client_secret và api_key.

client_secret và api_key chỉ được lưu ở backend/secret manager. Không đưa chúng vào browser bundle.

4. Bắt đầu đăng nhập

Backend tạo state ngẫu nhiên và PKCE code_verifier, sau đó chuyển trình duyệt tới authorize. Lưu cả hai trong session tạm thời.

GET https://apiauth.pages.dev/api/v1/oauth/authorize?client_id=...&redirect_uri=...&response_type=code&state=...&code_challenge=...&code_challenge_method=S256

5. Callback và token exchange

Callback nhận code và state. Backend kiểm tra state trước khi đổi code. Không thực hiện bước này ở frontend.

POST https://apiauth.pages.dev/api/v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=...&client_secret=...&code=...&redirect_uri=...&code_verifier=...

6. Redirect đúng direct URL

Auth API lấy direct_url từ project tương ứng với client_id. Website tích hợp tạo session riêng rồi chuyển user về URL đó.

7. Quy tắc tài khoản

Username dài 4-30 ký tự, chỉ gồm chữ thường, số và dấu gạch dưới.
Password tối thiểu 8 ký tự.
Confirm password phải khớp chính xác.
Username được kiểm tra realtime và kiểm tra lại ở backend.

8. Đăng xuất và revoke

POST https://apiauth.pages.dev/api/v1/auth/logout
POST https://apiauth.pages.dev/api/v1/oauth/revoke

Owner có thể revoke project trong dashboard. Không log authorization code, access token, client secret hoặc API key.

← Quay lại page test

Tích hợp xác thựckhông cần tự xây lại.