Xác thực và ủy quyền cho Ứng dụng

Để sử dụng hệ thống Zalo OA OpenAPI (Zalo OA, ZNS, Zalo Shop,...), ứng dụng của bạn cần được OA liên kết và cấp quyền bằng cách lấy mã Access Token (mã truy cập) từ OA đó.

Mỗi OA có giới hạn số lượng App được ủy quyền nhất định. Xem thông tin tại đây.

Tài liệu này hướng dẫn việc Xác thực và Ủy quyền cho ứng dụng theo 2 cách:

Sử dụng giao thức OAuth v4
Sử dụng công cụ Zalo API Explorer

Các thuật ngữ

Authorization code

Là mã ủy quyền từ OA cho phép ứng dụng gọi API để lấy Access Token và Refresh Token.
Authorization Code chỉ được sử dụng 1 lần và có hiệu lực trong vòng 10 phút (kể từ lúc được cấp).

Access token

Access Token cho phép ứng dụng đại điện OA sử dụng API.
Thời hạn hiệu lực của Access Token: 25 giờ (kể từ lúc được cấp mới).

Refresh token

Với mỗi Access Token được tạo ra sẽ luôn có một Refresh Token đi kèm.
Refresh Token được sử dụng để tạo lại Access Token khi Access Token hết hiệu lực.
Refresh Token chỉ được sử dụng một lần để tạo Access Token mới.
Sau khi sử dụng thành công, Refresh Token cũ sẽ bị vô hiệu hóa và hệ thống trả về Refresh Token mới cho lần refresh tiếp theo.
Access Token cũ sẽ hết hiệu lực ngay khi Access Token mới được tạo thành công.
Thời hạn hiệu lực của Refresh Token: 3 tháng (kể từ lúc được cấp mới).

Cách 1: Sử dụng giao thức OAuth v4

mẹo

Phương pháp này yêu cầu có kiến thức về lập trình, hiểu rõ code challenge và code verifier. Hoặc khi Doanh nghiệp sử dụng Ứng dụng của bên thứ 3

Lấy Access Token lần đầu

Sơ đồ tổng quan các bước yêu cầu cấp mới OA access token

Bước 1: Tạo code verifier và code challenge

Zalo sử dụng code challenge và code verifier (theo phương thức PKCE) để tăng độ bảo mật của quá trình xác thực và ủy quyền. Xem thêm về PKCE tại đây.

Trước khi thiết lập đường dẫn yêu cầu cấp quyền, bạn cần:

Tạo một code verifier và lưu trữ trên hệ thống của bạn.
Dùng mã hóa code verifier bằng bộ ký tự ASCII, tiếp đến dùng giải thuật SHA-256 để tạo mã băm, sau cùng encode Base64 (without Padding) mã băm để tạo ra code challenge từ code verifier.
code_challenge = Base64.encode(SHA-256.hash(ASCII(code_verifier)))

Lưu ý

Yêu cầu sử dụng code verifier khác nhau cho từng request.
Code verifier là 1 chuỗi bất kỳ, format có đủ chữ hoa, chữ thường, số và dài 43 ký tự.
Code verifier là code dùng để xác minh quyền sở hữu của bạn với authorization code bạn nhận được từ hệ thống. Vui lòng không cung cấp code này cho bên thứ ba.
Hãy dùng biến state hoặc một param tự định nghĩa truyền vào redirect_uri ở bước 3 để xác định authorization code mà bạn nhận được ứng với code verifier nào.

Bước 2: Thiết lập đường dẫn yêu cầu cấp quyền

Truy cập Zalo for Developers để thiết lập đường dẫn yêu cầu cấp quyền. Tại bước này, bạn cần thiết lập callback URL và tham số code challenge vừa được tạo ở bước 1. Sau khi truyền vào các tham số, vui lòng chọn các quyền cần được cấp và lưu lại các thiết lập.

Danh sách các nhóm quyền bạn có thể yêu cầu OA cấp:

Quyền gửi tin và thông báo qua OA
Quyền quản lý tin nhắn người dùng
Quyền quản lý thông tin OA
Quyền quản lý ads
Quyền quản lý bài viết
Quyền quản lý cửa hàng, đơn hàng
Quyền sử dụng chức năng gọi thoại
Quyền nhận sự kiện quản lý tin nhắn
Quyền nhận sự kiện quản lý người dùng

Xem chi tiết nhóm quyền và API tương ứng tại đây.

Lưu ý

Callback URL là nơi bạn sẽ phải thực hiện xử lý để nhận được authorization code. Trình duyệt sẽ chuyển hướng OA admin đến địa chỉ này sau khi quá trình ủy quyền từ phía OA admin hoàn tất.

Bước 3: Yêu cầu cấp authorization code

Sao chép đường dẫn yêu cầu cấp quyền và gửi đến admin của OA để bắt đầu quá trình nhận authorization code.

Đường dẫn sẽ mở trang cấp quyền cho ứng dụng như bên dưới:

Tại đây, Admin chọn tài khoản OA cần cấp quyền và chọn “Cho phép” để xác nhận cấp quyền. Trình duyệt sẽ chuyển hướng và gửi authorization code về callback URL đã được thiết lập trước đó (callback URL của bạn sẽ nhận được 1 HTTP get request có kèm authorization code và OA ID).

Lưu ý

Mỗi OA có giới hạn số lượng App được ủy quyền nhất định. Xem thông tin tại đây.

Ví dụ: callback URL của bạn là https://yourdomain.com/abc.HTTP get request sẽ gọi đến callback URL là:

https://yourdomain.com/abc?code=<AUTHORIZATION_CODE>&oa_id=<OA_ID>

Bước 4: Gửi API để lấy oa access token từ authorization code

Sử dụng API sau để lấy oa access token từ authorization code mà bạn nhận được.

HTTP request

URL: https://oauth.zaloapp.com/v4/oa/access_token
Method: POST
Content Type: application/x-www-form-urlencoded

Example request

curl \
-X POST \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'secret_key: <your_secret_key>' \
--data-urlencode 'code=<your_oauth_code>' \
--data-urlencode 'app_id=<your_app_id>' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code_verifier=your_code_verifier' \
'https://oauth.zaloapp.com/v4/oa/access_token'

Tham số	Kiểu dữ liệu	Tính bắt buộc	Mô tả
secret_key	string	yes	Khóa bí mật của ứng dụng. Xem hướng dẫn chi tiết tại đây.

Cấu trúc body

Tham số	Kiểu dữ liệu	Tính bắt buộc	Mô tả
code	string	yes	Authorization code mà bạn nhận được ở bước 3
app_id	long	yes	ID của ứng dụng
grant_type	string	yes	Thuộc tính cho biết thông tin để tạo access token. Giá trị nhận vào: · authorization_code: tạo access token từ authorization code.
code_verifier	string	yes nếu ở bước 2 có thiết lập code challenge	Code verifier được dùng để tạo code challenge ở bước 2.

Example response

{
    "access_token": "RfBh5NdqsWzhcX8bDDe_1A463Z34Fhy1GVi63AoTU1InwujqF",
    "refresh_token":"L2Y2BO9Prn_I1SkM08T4J99bZQYVbOBPfTVeRgrLdPK4ZqGX9G",
    "expires_in": "90000"
}

Thuộc tính

Tham số	Kiểu dữ liệu	Mô tả
access_token	string	Access token dùng để gọi các Official Account API Hiệu lực: 25 giờ
refresh_token	string	Mỗi access token được tạo sẽ có một refresh token đi kèm. Refresh token cho phép bạn tạo lại access token mới khi access token hiện tại hết hiệu lực. Refresh token chỉ có thể sử dụng 1 lần. Xem hướng dẫn tạo access token mới từ refresh token tại đây. Hiệu lực: 3 tháng
expire_in	string	Thời hạn của access token (đơn vị tính: giây)

Tham số

Kiểu dữ liệu

Mô tả

access_token

string

Access token dùng để gọi các Official Account API

Hiệu lực: 25 giờ

refresh_token

string

Mỗi access token được tạo sẽ có một refresh token đi kèm. Refresh token cho phép bạn tạo lại access token mới khi access token hiện tại hết hiệu lực. Refresh token chỉ có thể sử dụng 1 lần.

Xem hướng dẫn tạo access token mới từ refresh token tại đây.

Hiệu lực: 3 tháng

expire_in

string

Thời hạn của access token (đơn vị tính: giây)

Bước 5: Sử dụng oa access token để gọi API

Sử dụng access token để gọi các API của OA.

Dùng Refresh Token để lấy Access Token

Với mục đích năng cao tính bảo mật, bảo đảm an toàn thông tin, Access Token chỉ có hiệu lực trong 25 giờ kể từ khi được cấp, Ứng dụng cần gọi API sau đây để được cấp mới Access Token từ Refresh Token. Vòng lặp này có thể được thực hiện nhiều lần cho tới khi Ứng dụng bạn dừng gọi cấp mới Access Token từ Refresh Token.

HTTP request

URL: https://oauth.zaloapp.com/v4/oa/access_token
Method: POST
Content Type: application/x-www-form-urlencoded
Response Type: json

Example request

curl \
-X POST \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'secret_key: <your_secret_key>' \
--data-urlencode 'refresh_token=<your_refresh_token>' \
--data-urlencode 'app_id=<your_app_id>' \
--data-urlencode 'grant_type=refresh_token' \
'https://oauth.zaloapp.com/v4/oa/access_token'

Tham số header

Tham số	Kiểu dữ liệu	Tính bắt buộc	Mô tả
secret_key	string	yes	Khóa bí mật của ứng dụng. Xem hướng dẫn chi tiết tại đây.

Cấu trúc body

Tham số	Kiểu dữ liệu	Tính bắt buộc	Mô tả
refresh_token	string	yes	Refresh token dùng để tạo access token mới.
app_id	long	yes	ID của ứng dụng.
grant_type	string	yes	Thuộc tính cho biết thông tin để tạo access token. Giá trị nhận vào: · refresh_token: tạo access token từ refresh token.

Tham số

Kiểu dữ liệu

Tính bắt buộc

Mô tả

refresh_token

string

yes

Refresh token dùng để tạo access token mới.

app_id

long

yes

ID của ứng dụng.

grant_type

string

yes

Thuộc tính cho biết thông tin để tạo access token. Giá trị nhận vào:

· refresh_token: tạo access token từ refresh token.

Example respond

{
    "access_token":"E5sPAxHWmF9aYZeZzPczEcNRtdVIPCD3XyGXw1uLBZ3npsF-MUW",
    "refresh_token": "DCcFKjWctu458dAU2FRbaNRPCcQGZ34zCmUF9aYEcNRtdVIaq",
    "expires_in": "90000"
}

Mô tả thuộc tính

Thuộc tính	Kiểu dữ liệu	Mô tả
access_token	string	Access token dùng để gọi các Official Account API Hiệu lực: 25 giờ
refresh_token	string	Mỗi access token được tạo sẽ có một refresh token đi kèm. Refresh token cho phép bạn tạo lại access token mới khi access token hiện tại hết hiệu lực. Refresh token chỉ có thể sử dụng 1 lần. Hiệu lực: 3 tháng
expire_in	string	Thời hạn của access token (đơn vị tính: giây)

Thuộc tính

Kiểu dữ liệu

Mô tả

access_token

string

Access token dùng để gọi các Official Account API

Hiệu lực: 25 giờ

refresh_token

string

Hiệu lực: 3 tháng

expire_in

string

Thời hạn của access token (đơn vị tính: giây)

Cách 2: Sử dụng công cụ Zalo API Explorer

mẹo

Phương pháp này chỉ sử dụng khi bạn là

Admin của OA muốn lấy mã xác thực
Admin của Ứng dụng dùng để lấy mã xác thực

Lấy Access Token

Vào phần Công cụ & Hỗ trợ > API Explorertrên trang Zalo for Developers.

Chọn Ứng dụng

Chọn Loại Access Token là OA Access Token

Chọn Zalo Official Account (OA)

Kiểm tra các quyền ứng dụng yêu cầu được cấp và click Cho phép

Sao chép access token và sử dụng access token để gọi các OA API

Lấy Refresh Token

Tương tự Bước 1 tới Bước 5 của “Lấy Access Token” bằng công cụ Zalo API Explorer, tại bước 6:

Copy refresh token và cập nhật vào hệ thống để bắt đầu vòng lặp lấy access token

Các thuật ngữ​

Cách 1: Sử dụng giao thức OAuth v4​

Lấy Access Token lần đầu​

Bước 1: Tạo code verifier và code challenge​

Bước 2: Thiết lập đường dẫn yêu cầu cấp quyền​

Bước 3: Yêu cầu cấp authorization code​

Bước 4: Gửi API để lấy oa access token từ authorization code​

HTTP request​

Example request​

Tham số header​

Cấu trúc body​

Example response​

Thuộc tính​

Bước 5: Sử dụng oa access token để gọi API​

Dùng Refresh Token để lấy Access Token​

HTTP request​

Example request​

Tham số header​

Cấu trúc body​

Example respond​

Mô tả thuộc tính​

Cách 2: Sử dụng công cụ Zalo API Explorer​

Lấy Access Token​

Lấy Refresh Token​

Các thuật ngữ

Cách 1: Sử dụng giao thức OAuth v4

Lấy Access Token lần đầu

Bước 1: Tạo code verifier và code challenge

Bước 2: Thiết lập đường dẫn yêu cầu cấp quyền

Bước 3: Yêu cầu cấp authorization code

Bước 4: Gửi API để lấy oa access token từ authorization code

HTTP request

Example request

Tham số header

Cấu trúc body

Example response

Thuộc tính

Bước 5: Sử dụng oa access token để gọi API

Dùng Refresh Token để lấy Access Token

HTTP request

Example request

Tham số header

Cấu trúc body

Example respond

Mô tả thuộc tính

Cách 2: Sử dụng công cụ Zalo API Explorer

Lấy Access Token

Lấy Refresh Token