Logo Chuột APIChuột API

CHUỘT API / DEVELOPER DOCUMENTATION

Hướng dẫn tích hợp Google OAuth Account Chooser

Tài liệu này giải thích cách đưa chức năng đăng nhập Google vào một website khác bằng credentials do Chuột API cấp. Người dùng sẽ nhìn thấy Google Account Chooser, còn website của bạn nhận được access token đại diện đúng tài khoản đã chọn.

Cập nhật: 04/09/2026 · Chuẩn OAuth 2.0 authorization code

Chuột API giải quyết vấn đề gì?

Chuột API là nền tảng xác thực trung gian. Website của bạn không cần tự xây toàn bộ giao diện chọn tài khoản và không cần lưu mật khẩu Google. Bạn đăng ký một project, nhận credentials, chuyển người dùng sang endpoint authorize, rồi đổi authorization code ở backend để lấy access token.

Google Account ChooserGoogle được gọi với prompt=select_account.
Credentials riêngMỗi project có Client ID, Client Secret, API key và Direct URL.
Profile chuẩnGọi /me để nhận Gmail, tên và avatar.

Bắt đầu tích hợp

1. Tạo project và lấy credentials

  1. Mở Chuột API Console và đăng nhập bằng tài khoản Google quản trị.
  2. Vào tab API project, nhập tên project và Direct URL của website bạn.
  3. Lưu API key, Client ID và Client Secret. Client Secret chỉ lưu ở backend.

2. Các URL production

Authorize endpoint
https://apiserverauth.pages.dev/oauth/authorize
Token endpoint
https://apiserverauth.pages.dev/oauth/token
API base URL
https://apiserverauth.pages.dev/api/v1
Google callback của Chuột API
https://apiserverauth.pages.dev/oauth/google/callback

Luồng Google Account Chooser

Website gửi trình duyệt tới Authorize endpoint với ba tham số bắt buộc: client_id, redirect_uri và state. Direct URL phải khớp tuyệt đối với URL đã đăng ký trong project.

  1. Authorize: website bắt đầu OAuth với Client ID và Direct URL.
  2. Choose: Chuột API chuyển người dùng sang Google; Google hiển thị Account Chooser.
  3. Callback: sau khi chọn tài khoản, Chuột API chuyển authorization code về Direct URL.
  4. Exchange: backend dùng Client Secret đổi code tại Token endpoint.
  5. Identify: backend dùng access token gọi API profile.

Vai trò của từng credential

CredentialDùng để làm gìNơi lưu
Client IDNhận diện project khi bắt đầu OAuth.Frontend có thể biết, nhưng nên cấu hình từ server.
Client SecretXác thực backend khi đổi authorization code lấy access token.Chỉ backend/secret manager.
API keyXác thực project khi gọi API server-to-server.Chỉ backend/secret manager.
Access tokenĐại diện tài khoản Google đã chọn để gọi /me.Session backend, không đưa vào URL.

API reference

GET /api/v1/me

Lấy profile người dùng hiện tại. Dùng Bearer API key sẽ trả chủ project; dùng Bearer OAuth access token sẽ trả người dùng vừa đăng nhập.

GET https://apiserverauth.pages.dev/api/v1/me
Authorization: Bearer <api_key_or_access_token>

GET /api/v1/models

Kiểm tra credential và liệt kê resource model hiện có.

GET https://apiserverauth.pages.dev/api/v1/models
Authorization: Bearer <api_key>

POST /oauth/token

Đổi authorization code một lần. Request phải gửi form URL-encoded từ backend.

grant_type=authorization_code
code=authz_...
client_id=clt_...
client_secret=cls_...
redirect_uri=https://your-site.example/auth/callback

POST /api/v1/applications

Endpoint dành cho console đã đăng nhập để tạo project credentials, không gọi từ website khách.

Bảo mật và vận hành

  • Luôn dùng HTTPS cho Direct URL.
  • Tạo và kiểm tra state bằng giá trị ngẫu nhiên để chống CSRF.
  • Đổi authorization code ngay một lần; code hết hạn hoặc đã dùng sẽ bị từ chối.
  • Không log API key, Client Secret, authorization code hoặc access token.
  • Lưu token trong server session và đặt cookie HttpOnly, Secure.
  • Dùng Revoke khi project hoặc credentials bị lộ; thao tác này xóa project, callback, credentials và activity liên quan.

Lỗi tích hợp thường gặp

400 invalid_request

Thiếu tham số hoặc gửi sai grant_type/Content-Type. Kiểm tra body token request là application/x-www-form-urlencoded.

400 invalid_grant

Code sai, đã dùng hoặc hết hạn. Bắt đầu lại flow OAuth, không reload callback cũ.

401 invalid_client

Client ID, Client Secret hoặc Direct URL không khớp cùng một project. So sánh từng ký tự và scheme HTTPS.

redirect_uri_mismatch

Google chưa cho phép callback của Chuột API hoặc callback bị viết sai. Callback bắt buộc là https://apiserverauth.pages.dev/oauth/google/callback.

401 Authentication required

Endpoint quản trị như applications/overview cần session đăng nhập console, không dùng API key của website khách.

1101 Worker exception

Thường là callback function bị lỗi runtime hoặc deployment cũ. Kiểm tra callback URL tuyệt đối, secret runtime và deploy mới nhất.

Checklist trước khi đưa vào production

  1. Direct URL đã truy cập được bằng HTTPS.
  2. Client ID, Client Secret và API key thuộc cùng project.
  3. Authorize redirect tạo được Account Chooser.
  4. Backend đổi code thành công tại /oauth/token.
  5. Access token gọi được /api/v1/me và trả đúng Gmail.
  6. Website xử lý lỗi, timeout và logout.
  7. Đã thử revoke credential trong môi trường test.