Zalo access token: Cách lấy, làm mới và gọi API an toàn

Zalo access token là thông tin xác thực bắt buộc khi ứng dụng muốn đại diện Zalo Official Account để gọi OpenAPI. Token cho phép backend đọc thông tin OA, quản lý một số nghiệp vụ và triển khai quy trình tự động trong phạm vi đã được cấp quyền.

Việc tích hợp không nên chỉ dừng ở thao tác sao chép một chuỗi token vào mã nguồn. Lập trình viên cần hiểu luồng OAuth, thời hạn sử dụng, cách làm mới bằng refresh token, phương án lưu trữ và cách xử lý khi quyền bị thu hồi. Bài viết này tập trung vào OA Access Token dành cho Zalo OA và các API liên quan.

Zalo access token là gì và dùng để làm gì?

Zalo access token là chuỗi xác thực cho phép ứng dụng gọi những API được bảo vệ của Zalo. Trong hệ thống OA OpenAPI, token đại diện cho sự ủy quyền giữa một ứng dụng trên Zalo for Developers và một Zalo Official Account cụ thể.

Luồng cấp quyền thường có bốn thành phần: người quản trị OA, Zalo OA, ứng dụng đã đăng ký và máy chủ backend. Người quản trị chấp thuận quyền truy cập, Zalo trả authorization code về callback URL, sau đó backend đổi code thành access token và refresh token.

Ba loại mã cần phân biệt gồm:

• Authorization code: mã ngắn hạn, dùng một lần để lấy bộ token ban đầu.
• Access token: mã dùng trực tiếp khi gửi request đến OA API.
• Refresh token: mã dùng để tạo access token mới khi token cũ gần hết hạn.

Token không phải mật khẩu Zalo nhưng vẫn là dữ liệu nhạy cảm. Bên sở hữu token hợp lệ có thể thực hiện các hành động mà ứng dụng đã được cho phép. Token cũng gắn với đúng ứng dụng và OA đã cấp quyền, vì vậy không thể tùy ý dùng token của OA này để thao tác OA khác.

Access token không giúp vượt qua hạn mức, chính sách gửi tin hoặc điều kiện sử dụng API. Mỗi endpoint vẫn có phương thức, tham số, quyền và giới hạn riêng mà hệ thống phải tuân thủ.

Chuẩn bị ứng dụng và OA trước khi tạo token

Trước khi lấy token, hãy tạo ứng dụng trên Zalo for Developers và hoàn thiện cấu hình kỹ thuật. Các lỗi App ID, callback URL hoặc quyền quản trị OA thường bắt nguồn từ bước chuẩn bị chưa đầy đủ.

Tạo ứng dụng và cấu hình callback URL

Sau khi tạo ứng dụng, lưu App ID và secret key trong kho bí mật của backend. Khai báo callback URL là endpoint nhận authorization code sau khi quản trị viên hoàn tất cấp quyền.

Callback URL phải khớp chính xác với cấu hình trên hệ thống. Khác biệt về HTTP và HTTPS, tên miền, cổng, đường dẫn hoặc dấu gạch chéo cuối URL đều có thể làm quá trình xác thực thất bại.

Kiểm tra quyền quản trị Zalo OA

Người thực hiện cấp quyền phải có quyền quản lý OA tương ứng. Khi mở trang ủy quyền, họ chọn đúng OA và chấp thuận các quyền ứng dụng cần sử dụng.

Chỉ yêu cầu phạm vi quyền phù hợp với nghiệp vụ. Một tích hợp chỉ đọc thông tin OA không nên xin thêm quyền gửi tin hoặc quản lý chức năng không liên quan. Nguyên tắc quyền tối thiểu giúp giảm hậu quả nếu token bị lộ.

Chuẩn bị PKCE và state

Luồng OAuth OA sử dụng PKCE. Backend tạo một chuỗi ngẫu nhiên làm code verifier, sau đó tạo code challenge từ SHA-256 và Base64 URL-safe. Code verifier phải được lưu tạm cho đúng phiên cấp quyền.

Khi callback nhận authorization code, backend gửi lại code verifier ban đầu. Nếu verifier không khớp, yêu cầu đổi token sẽ thất bại. Ngoài ra, nên tạo tham số state ngẫu nhiên và kiểm tra lại khi callback trả về để hạn chế request giả mạo.

Cách lấy Zalo access token cho Zalo OA

Có thể lấy token bằng luồng OAuth hoặc dùng API Explorer để thử nhanh. Với hệ thống vận hành thực tế, OAuth phía backend là phương án phù hợp vì có thể quản lý vòng đời token tự động.

Lấy token bằng authorization code

Quy trình cơ bản gồm:

1. Backend tạo code verifier, code challenge và state.
2. Ứng dụng chuyển người quản trị đến trang cấp quyền Zalo.
3. Người quản trị đăng nhập, chọn OA và xác nhận quyền.
4. Zalo chuyển hướng về callback URL cùng authorization code.
5. Backend kiểm tra state rồi đổi code lấy access token và refresh token.
6. Hệ thống lưu token, OA ID và thời điểm hết hạn.

Endpoint đổi token của OA:

POST https://oauth.zaloapp.com/v4/oa/access_token

Request dùng application/x-www-form-urlencoded. Secret key được truyền trong header, còn App ID, authorization code, grant type và code verifier nằm trong body. Cấu trúc cURL tham khảo:

curl –request POST
–url https://oauth.zaloapp.com/v4/oa/access_token
–header “Content-Type: application/x-www-form-urlencoded”
–header “secret_key: YOUR_APP_SECRET”
–data-urlencode “app_id=YOUR_APP_ID”
–data-urlencode “code=AUTHORIZATION_CODE”
–data-urlencode “grant_type=authorization_code”
–data-urlencode “code_verifier=ORIGINAL_CODE_VERIFIER”

Backend cần đổi authorization code ngay khi nhận được callback. Code có hiệu lực ngắn và chỉ nên dùng một lần. Không chuyển secret key, code verifier hoặc refresh token xuống trình duyệt để JavaScript xử lý.

Khi nhận response, hãy kiểm tra mã lỗi và các trường bắt buộc trước khi lưu. Không ghi toàn bộ response chứa token vào log, công cụ theo dõi lỗi hoặc tin nhắn nội bộ.

Thời hạn và cách làm mới Zalo access token

OA access token có thời hạn 25 giờ. Refresh token đi kèm có thời hạn 3 tháng kể từ lúc được cấp mới. Access token ngắn hạn làm giảm thời gian khai thác nếu bị lộ, còn refresh token giúp ứng dụng duy trì kết nối mà không phải xin cấp quyền lại mỗi ngày.

Hệ thống nên lưu expires_at và chủ động refresh trước khi access token hết hạn khoảng 10 đến 30 phút. Không đợi mọi request đồng loạt báo lỗi mới bắt đầu làm mới.

Gọi API bằng refresh token

Để lấy bộ token mới, gửi POST đến cùng endpoint nhưng đổi grant type:

curl –request POST
–url https://oauth.zaloapp.com/v4/oa/access_token
–header “Content-Type: application/x-www-form-urlencoded”
–header “secret_key: YOUR_APP_SECRET”
–data-urlencode “app_id=YOUR_APP_ID”
–data-urlencode “grant_type=refresh_token”
–data-urlencode “refresh_token=CURRENT_REFRESH_TOKEN”

Sau khi refresh thành công, phải cập nhật cả access token và refresh token được trả về. Không mặc định rằng refresh token cũ vẫn dùng được, vì cơ chế xoay token có thể làm giá trị trước mất hiệu lực.

Bản ghi token nên có App ID, OA ID, access token đã mã hóa, refresh token đã mã hóa, thời điểm hết hạn và thời điểm cập nhật. Với hệ thống nhiều worker, cần khóa phân tán hoặc optimistic locking để tránh hai tiến trình cùng refresh.

Xử lý refresh an toàn

Luồng phù hợp là kiểm tra hạn trước khi gọi API. Nếu token còn đủ thời gian, tiếp tục request. Nếu gần hết hạn, chỉ một worker thực hiện refresh; các worker khác chờ và đọc lại token mới.

Cách dùng access token để gọi Zalo OA API

Mỗi OA API có yêu cầu riêng, nhưng access token thường được truyền trong header theo tài liệu của endpoint. Ví dụ lấy thông tin OA:

curl –request GET
–url https://openapi.zalo.me/v3.0/oa/getoa
–header “access_token: YOUR_OA_ACCESS_TOKEN”

Trong production, nên xây dựng một API client dùng chung. Client chịu trách nhiệm lấy token hiện hành, gắn header, đặt timeout, phân loại lỗi, refresh khi cần và che dữ liệu nhạy cảm trong log.

Ví dụ gọi API bằng Node.js

async function getOfficialAccount(accessToken) {
const response = await fetch(“https://openapi.zalo.me/v3.0/oa/getoa”, {
method: “GET”,
headers: ,
signal: AbortSignal.timeout(10000)
});

const data = await response.json();

if (!response.ok || data.error) {
throw new Error(Zalo API error: ${data.error ?? response.status});
}

return data;
}

Backend phải tự xác định OA thuộc khách hàng hoặc tenant nào, sau đó lấy đúng token của OA đó. Không nhận token tùy ý từ người dùng cuối rồi chuyển tiếp đến Zalo API.

Retry và giám sát lỗi

Lỗi mạng, timeout hoặc lỗi máy chủ tạm thời có thể retry với exponential backoff. Lỗi đầu vào, thiếu quyền, token không hợp lệ hoặc vượt hạn mức phải được xử lý theo nguyên nhân thay vì thử lại liên tục.

Log nên chứa endpoint, OA ID nội bộ, mã lỗi, thời gian phản hồi và correlation ID. Không ghi nguyên access token, refresh token, secret key hoặc authorization code. Với nghiệp vụ có tác động như gửi tin, cần cơ chế chống gửi trùng khi request bị timeout.

Bảo mật và lỗi thường gặp khi dùng token

Token phải được xem như thông tin đăng nhập của dịch vụ. Access token bị lộ có thể bị lợi dụng trong thời gian còn hiệu lực; refresh token bị lộ còn nguy hiểm hơn vì có thể tạo token mới.

Nguyên tắc bảo mật quan trọng

• Chỉ xử lý authorization code và token ở backend qua HTTPS.
• Lưu secret key và token trong secret manager hoặc dữ liệu đã mã hóa.
• Không hardcode token trong Git, Docker image, ứng dụng mobile hoặc JavaScript phía client.
• Tách token theo từng OA, ứng dụng và môi trường.
• Che token trong log, ảnh chụp màn hình, công cụ APM và thông báo lỗi.
• Giới hạn quyền truy cập của nhân sự và dịch vụ nội bộ.
• Cảnh báo khi refresh thất bại hoặc tỷ lệ lỗi API tăng bất thường.
• Cấp quyền lại và thay thông tin xác thực khi nghi ngờ rò rỉ.

Nếu có trang quản trị nội bộ, chỉ hiển thị một phần token và ghi audit log khi người dùng thực hiện thao tác nhạy cảm. Không để toàn bộ refresh token hiển thị cho nhiều nhân viên.

Các lỗi phổ biến

Access token is invalid: Kiểm tra token bị thiếu ký tự, có khoảng trắng, lấy nhầm User Access Token hoặc thuộc OA khác. Đồng thời kiểm tra đúng tên header.

Access token hết hạn hoặc bị xóa: Dùng refresh token hiện hành để lấy bộ token mới. Nếu refresh thất bại, yêu cầu người quản trị cấp quyền lại.

Invalid refresh token: Có thể token đã hết hạn, đã được thay thế, lưu sai hoặc bị hai worker sử dụng đồng thời. Kiểm tra lịch sử cập nhật và khóa quá trình refresh.

Sai App ID hoặc secret key: Đối chiếu đúng ứng dụng và môi trường. Không dùng App ID staging với secret key production.

Authorization code không hợp lệ: Code có thể đã hết hạn, đã dùng hoặc code verifier không khớp. Hãy khởi động lại luồng ủy quyền thay vì gửi lại cùng code.

Callback URL không khớp: Kiểm tra HTTPS, domain, cổng, đường dẫn và cấu hình proxy. URL thực tế phải phù hợp với URL đã khai báo.

OA không đủ quyền: Xác nhận người cấp quyền đang quản lý đúng OA, OA vẫn hoạt động và ứng dụng được phép dùng API tương ứng.

Câu hỏi thường gặp

Có thể dùng một token cho nhiều OA không?

Không. Hệ thống quản lý nhiều OA cần lưu và chọn đúng bộ token cho từng OA đã cấp quyền.

Refresh token hết hạn thì làm gì?

Thực hiện lại luồng OAuth để nhận authorization code và bộ token mới. Nên có cảnh báo và màn hình kết nối lại OA.

Kết luận về Zalo access token

Tích hợp Zalo OA ổn định đòi hỏi quản lý đầy đủ vòng đời token: cấp quyền bằng OAuth và PKCE, đổi authorization code ở backend, lưu an toàn bộ token, làm mới trước hạn và cấp quyền lại khi refresh token không còn hợp lệ xem thêm tại zalo web.

Bên cạnh việc gọi đúng endpoint, hệ thống cần khóa đồng thời khi refresh, cập nhật token nguyên tử, phân loại lỗi và tuyệt đối không để token xuất hiện trong mã nguồn hoặc log. Khi triển khai đúng các nguyên tắc này, Zalo access token sẽ trở thành nền tảng xác thực đáng tin cậy cho việc vận hành OA và kết nối Zalo API lâu dài.