# Auth SDK: đăng ký, phiên và khôi phục

Danh tính nằm riêng trong từng Project; tài khoản WhyPik dashboard không phải tài khoản của ứng dụng.

Nguồn: https://whypik.com/docs/auth-reference
Nhóm: Lập trình viên
Phiên bản tài liệu: 2026-10-14.10
Ngôn ngữ: vi

## Khóa dùng cho website và Static Hosting

Liên kết mục: https://whypik.com/docs/auth-reference#section-0

Mở Authentication → API & SDK, chọn Public · Website / Static Hosting để tạo khóa wpk_public_. Khóa này được phép đặt trong JavaScript hoặc environment.ts của ứng dụng. Nó chỉ nhận diện dự án, không cấp quyền quản trị; quyền dữ liệu vẫn theo phiên người dùng và policy. Khi chưa đăng nhập, chỉ truy cập được dữ liệu có policy anonymous phù hợp. Public key tạo riêng ở Database không thay cho Public key của Authentication khi đăng nhập.

Trên WhyPik Static Hosting hoặc tên miền riêng đã xác minh và kích hoạt, SDK mặc định dùng /.whypik/auth và /.whypik/data cùng tên miền. WhyPik cung cấp backend Auth; ứng dụng tĩnh không cần tự chạy backend hoặc tạo khóa BFF. Bật Authentication, cho phép tên miền trong Cấu hình đăng nhập và triển khai trang callback của ứng dụng theo hướng dẫn Angular.

BFF · Backend riêng tạo khóa wpk_bff_ dành cho backend của website được host bên ngoài WhyPik khi cần phiên cookie bền. Không đặt khóa BFF, Data server secret wpk_secret_ hoặc khóa quản lý tài khoản wpc_ trong JavaScript, environment.ts hay ZIP website. Các khóa này khác Public key.

- [Tích hợp Angular từng bước](https://whypik.com/docs/angular-first-start)
- [Backend và BFF](https://whypik.com/docs/node-sdk)

## Quản trị viên ứng dụng đầu tiên

Liên kết mục: https://whypik.com/docs/auth-reference#section-1

Đăng ký trên website của bạn và xác minh email. Chủ Project mở Authentication → Người dùng, tìm email rồi bật Quản trị viên ứng dụng. Không cấp quyền chỉ từ một email chưa đăng ký hoặc metadata do client gửi.

is_admin là cờ đặc quyền dữ liệu duy nhất; không có phân cấp manager/staff. Tài khoản có role cũ tên admin không tự được nâng quyền. Chủ Project có thể thu hồi bằng cùng nút; API đọc trạng thái hiện hành, kể cả khi client giữ access token cũ.

client.auth.is_admin là giá trị chỉ đọc để hiện/ẩn giao diện. Cập nhật bằng getUser(), đăng nhập hoặc làm mới phiên; không có thông báo đẩy tự động. Ẩn nút không thay thế kiểm quyền phía server.

```
await client.auth.signInWithPassword({ email, password });
await client.auth.getUser();
if (client.auth.is_admin) {
  // Hiện điều hướng quản trị ứng dụng. API vẫn tự kiểm quyền.
}
```


## Lấy UUID và tải cấu hình client

Liên kết mục: https://whypik.com/docs/auth-reference#section-2

PROJECT_ID là Mã dự án dễ đọc, ví dụ hue-spa. PROJECT_UUID là UUID của dự án, dùng cho trường project của SDK và các đường dẫn API. Cả hai nằm ở Tổng quan dự án và Authentication → API & SDK; bấm biểu tượng sao chép cạnh PROJECT_UUID để lấy đúng giá trị; thông báo Đã sao chép. xác nhận thành công.

Tạo Public key rồi bấm Cấu hình client tại dòng khóa tương ứng. Chọn WhyPik Static Hosting hoặc Hosting bên ngoài WhyPik, sau đó Sao chép JSON, Tải JSON hoặc Tải .env. JSON có project, key, auth, data và dùng được với new WhyPik(config). Không chứa BFF key, server secret, khóa quản lý tài khoản, phiên đăng nhập hoặc thông tin bucket R2.

Public Auth key mới có thể tải lại khi còn hiệu lực. Khóa cũ chỉ lưu dạng băm nên không khôi phục được; giữ bản sao cũ hoặc tạo Public key mới để xuất cấu hình. Không tự thu hồi khóa cũ. Khóa đã hết hạn hoặc thu hồi không có nút xuất cấu hình.

WhyPik Hosting dùng endpoint tương đối /.whypik/auth và /.whypik/data, giữ phiên cookie cùng origin. Website bên ngoài dùng endpoint HTTPS của nền tảng và memory session; reload cần đăng nhập lại. Vẫn phải bật dịch vụ, khai báo origin và callback và cấu hình quyền dữ liệu; file tải xuống không tự cấp quyền.

.env chỉ chứa cấu hình public cho công cụ build. Ánh xạ WHYPIK_PROJECT_UUID → project, WHYPIK_PUBLIC_KEY → key, WHYPIK_AUTH_ENDPOINT → auth.endpoint, WHYPIK_AUTH_SESSION_MODE → auth.sessionMode, WHYPIK_AUTH_AUTO_RESTORE → auth.autoRestore (chuyển chuỗi sang boolean), WHYPIK_DATA_ENDPOINT → data.endpoint. WHYPIK_PROJECT_ID chỉ để nhận diện tên ngắn; không dùng thay UUID. Angular không tự nạp .env.


## Tên miền và callback trong cấu hình

Liên kết mục: https://whypik.com/docs/auth-reference#section-3

Mở Authentication của đúng dự án. Tên miền ứng dụng được phép là các origin HTTPS chính xác, không gồm đường dẫn hay query. Nhấn Enter hoặc dấu phẩy để thêm từng thẻ, dán nhiều dòng để thêm nhiều địa chỉ, bấm nút xóa ở thẻ để bỏ địa chỉ. Có thể bỏ tiền tố https:// khi nhập; hệ thống thêm HTTPS. Không nhận HTTP, wildcard, thông tin đăng nhập hoặc fragment. Tối đa 20 địa chỉ cho mỗi danh sách.

Lần cấu hình đầu, bỏ trống danh sách tên miền dùng địa chỉ mặc định của dự án. Địa chỉ này được cấp trước khi bật Hosting; nó không chứng minh website đã được triển khai. Nếu môi trường không có địa chỉ mặc định, bạn cần nhập origin HTTPS của ứng dụng.

Ví dụ Project ID spa có hostname spa.whypik.app: allowed_origins mặc định là ["https://spa.whypik.app"], redirect_urls mặc định là ["https://spa.whypik.app/auth/callback"]. Dùng hostname thực được cấp trong Tổng quan, gồm cả hậu tố tránh trùng nếu có; không dùng PROJECT_UUID làm subdomain.

Bật Tự tạo đường dẫn /auth/callback theo tên miền để danh sách callback đi theo các origin đã chọn. Tắt tùy chọn này khi cần route riêng và nhập URL callback chính xác; mọi callback phải thuộc origin được phép. URL tùy chỉnh đã lưu được giữ nguyên, không tự ghi đè thành /auth/callback. Bỏ trống danh sách callback đưa cấu hình về chế độ tự động.

Thêm tên miền Hosting hoặc DNS không tự cho phép origin trong Auth. Hãy thêm origin đó vào cấu hình Auth khi ứng dụng dùng nó. Xóa một origin sẽ thu hồi các phiên thuộc origin đã bỏ. Callback tự động chỉ cập nhật theo danh sách Auth, không tự tạo route hay triển khai trang.

| Trường cấu hình | Mặc định | Ví dụ dự án spa |
| --- | --- | --- |
| Tên miền ứng dụng được phép (allowed_origins) | https://<hostname mặc định của dự án> | https://spa.whypik.app |
| Đường dẫn xác nhận email được phép (redirect_urls) | Origin + /auth/callback | https://spa.whypik.app/auth/callback |

```
{
  "allowed_origins": ["https://spa.whypik.app"],
  "redirect_urls": ["https://spa.whypik.app/auth/callback"],
  "redirects_automatic": true
}
```

- [Ví dụ Angular và trang callback](https://whypik.com/docs/angular-first-start)

## Khởi tạo và phiên

Liên kết mục: https://whypik.com/docs/auth-reference#section-4

| API | Dùng khi nào |
| --- | --- |
| auth.ready | await để chờ khôi phục ban đầu theo cấu hình |
| auth.getSession() | Đọc Session hiện có ở client hoặc null; không chứng minh quyền trên server |
| auth.getUser() | Đọc ProjectUser từ server; lỗi xác thực không trả user giả |
| auth.getAccessToken({allowAnonymous:false}) | Lấy access token đã kiểm tra hạn; không lưu token vào localStorage |
| auth.restoreSession() | Khôi phục/refresh phiên; cookie mode cần HTTPS và điều phối tab |
| auth.onAuthStateChange(listener) | Nhận event/session; trả hàm hủy đăng ký |
| auth.destroy() / client.destroy() | Hủy request, timer, listener khi không còn dùng |


## Đăng ký và đăng nhập

Liên kết mục: https://whypik.com/docs/auth-reference#section-5

| API | Kết quả |
| --- | --- |
| auth.signUp({email,password,metadata?,redirect_url?}) | check_email; chưa cấp phiên đã xác minh |
| auth.signInWithPassword({email,password,device_label?}) | Session có user, accessExpiresAt, expiresAt, idleExpiresAt |
| auth.signInWithCustomToken(token) | Session hoặc check_email; chỉ JWT từ issuer đã cấu hình |
| auth.signOut({scope:"current"}) | Đăng xuất phiên hiện tại; scope:"all" cho mọi phiên của user |
| auth.listSessions() | {sessions:[...]} của người đang đăng nhập |
| auth.revokeSession(session_id) | Thu hồi một phiên của chính user |


## Hành động email

Liên kết mục: https://whypik.com/docs/auth-reference#section-6

| API | Nội dung |
| --- | --- |
| auth.sendEmailVerification({email,redirect_url?}) | Gửi lại xác minh |
| auth.verifyEmail(token) | Xác nhận purpose verify |
| auth.requestPasswordReset({email,redirect_url?}) | Yêu cầu đặt lại mật khẩu, không tiết lộ email có tồn tại |
| auth.resetPassword({token,password}) | Xác nhận purpose reset |
| auth.updatePassword({current_password,password}) | Đổi mật khẩu khi đăng nhập; cần đăng nhập lại sau thành công |
| auth.requestEmailChange({email,current_password,redirect_url?}) | Yêu cầu thay email |
| auth.confirmEmailChange(token) | Xác nhận purpose email_change |
| auth.acceptInvitation({token,password}) | Nhận lời mời purpose invite |


## Callback và trạng thái

Liên kết mục: https://whypik.com/docs/auth-reference#section-7

takeEmailAction() trả {token,purpose} hoặc null và xóa tham số hành động khỏi fragment. Gọi trước analytics; giữ token trong bộ nhớ rồi yêu cầu bấm xác nhận. Không tiêu thụ token bằng GET. ActionResult có status và sign_in_required; tuân theo kết quả, không giả định đã login.

Event: SIGNED_IN, REFRESHED, SIGNED_OUT, USER_UPDATED, SESSION_CHANGED. getSession không chứa refresh credential. Với signOut, serverConfirmed:false nghĩa là chỉ xóa phiên cục bộ khi mất mạng, chưa chứng minh đã thu hồi trên server.


## Phiên bền và giới hạn

Liên kết mục: https://whypik.com/docs/auth-reference#section-8

Default cùng origin: /.whypik/auth. Cookie Secure/HttpOnly, chỉ hostname hiện tại; không dùng cookie dashboard cho app. Memory mode mất phiên khi reload. Website ở nơi khác cần BFF cùng origin để dùng cookie bền.

Các hạn mức Auth thương mại chưa chốt. Giới hạn thử nghiệm là cấu hình vận hành hữu hạn, không phải cam kết số user theo Free/Starter/Pro hay unlimited. Xem số liệu/giới hạn thực tại Authentication.


## Hợp đồng cấu hình callback qua API quản lý

Liên kết mục: https://whypik.com/docs/auth-reference#section-9

Backend gọi GET/PATCH /api/v1/cloud/projects/PROJECT_UUID/auth bằng Cloud key: cần auth:read và thêm auth:settings:write khi PATCH. Dashboard dùng đường dẫn /api/v1/seller/cloud/projects/PROJECT_UUID/auth với session + CSRF. Không gọi API quản lý này bằng public Auth key của ứng dụng.

Các trường liên quan là allowed_origins (mảng origin), redirect_urls (mảng URL đầy đủ) và redirects_automatic (boolean). Khi tạo cấu hình lần đầu, bỏ qua hoặc gửi mảng origin rỗng dùng hostname mặc định; bỏ qua callback hoặc gửi mảng callback rỗng dùng origin + /auth/callback. Callback tự động dùng /auth/callback; callback tùy chỉnh đã lưu giữ nguyên.

Ở lần sửa sau, bỏ qua origin và callback giữ giá trị đã lưu; redirects_automatic:true tạo lại callback từ các origin hiệu lực. Với callback tùy chỉnh, gửi redirects_automatic:false và redirect_urls không rỗng. Gửi callback rỗng luôn trở về tự động. Việc cho phép callback không triển khai trang nhận token; ứng dụng vẫn phải thực hiện luồng takeEmailAction và xác nhận đúng purpose.

Khi SDK không truyền redirect_url, server chọn URL đầu tiên trong redirect_urls đã lưu. Khi truyền redirect_url, URL phải khớp chính xác một mục được cho phép. Khai báo allowlist không tự tạo route hoặc kích hoạt Hosting.


## Đọc tiếp

- [First Start: tích hợp Angular](https://whypik.com/docs/angular-first-start)
- [Đăng nhập từ hệ thống có sẵn](https://whypik.com/docs/auth-custom-token)
- [Node, SSR và BFF](https://whypik.com/docs/node-sdk)
- [Lỗi, timeout và chẩn đoán SDK](https://whypik.com/docs/sdk-errors)