---
sourceType: official-guide
sourceTypeMatchedRule: fallback
slug: OA/bat-dau/xac-thuc-va-uy-quyen-cho-ung-dung-new
title: Xác thực và ủy quyền cho Ứng dụng
---
# 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](https://zalo.solutions/oa/pricing).

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: 

1. Sử dụng giao thức OAuth v4 
2. 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 là loại mã sử dụng 1 lần, sau khi thành công sử dụng để tạo Access Token mới, Refresh Token sẽ hết hiệu lực (Tuy nhiên bạn cũng sẽ nhận được 1 mới Refresh Token đi kèm để sử dụng cho lần tạo lại Access Token tiếp theo).
* 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 
:::tip
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


![](/assets/OA/img/access_token.png)

{/* ![](/assets/OA/img/access_token.png) */}

#### 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](https://www.oauth.com/oauth2-servers/pkce/).

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)))`

:::warning 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](/docs/OA/bat-dau/gioi-thieu-official-account-api-va-cac-nhom-quyen).

:::warning 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.
:::

![](/assets/OA/img/app_request_perm_oa_1.jpg)

#### 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. 
![](/assets/OA/img/duong_dan.png)

Đường dẫn sẽ mở trang cấp quyền cho ứng dụng như bên dưới:
![](/assets/OA/img/uy_quyen_1.jpg)

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).

:::info 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](https://zalo.solutions/oa/pricing).
:::

Ví dụ: callback URL của bạn là [https://yourdomain.com/abc](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  
](http://oauth.zaloapp.com/v4/oa/access_token)
- **Method**: POST
- **Content Type**: application/x-www-form-urlencoded

##### Example request

```bash
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ố header


    
| Tham số | Kiểu dữ liệu | Tính bắt buộc | Mô tả |
| --- | --- | --- | --- |
| [secret_key](/docs/OA/phu-luc/huong-dan-lay-khoa-bi-mat-cua-ung-dung) | string | yes | Khóa bí mật của ứng dụng. Xem hướng dẫn chi tiết [tại đây](/docs/OA/phu-luc/huong-dan-lay-khoa-bi-mat-cua-ung-dung). |



###### 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

```json
{
    "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](/docs/OA/bat-dau/xac-thuc-va-uy-quyen-cho-ung-dung-new). 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
```bash
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](/docs/OA/phu-luc/huong-dan-lay-khoa-bi-mat-cua-ung-dung) | string | yes | Khóa bí mật của ứng dụng. Xem hướng dẫn chi tiết [tại đây](/docs/OA/phu-luc/huong-dan-lay-khoa-bi-mat-cua-ung-dung). |



###### 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. |



##### Example respond
```json
{
    "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) |



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

:::tip
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.
![](/assets/OA/img/tool1.png)

{/* ![](/assets/OA/img/tool1.png) */}

- Chọn Ứng dụng
![](/assets/OA/img/tool2.png)

{/* ![](/assets/OA/img/tool2.png) */}

- Chọn Loại Access Token là OA Access Token
![](/assets/OA/img/tool3.png)

{/* ![](/assets/OA/img/tool3.png) */}

- Chọn Zalo Official Account (OA) 
![](/assets/OA/img/tool4.png)

{/* ![](/assets/OA/img/tool4.png) */}

- Kiểm tra các quyền ứng dụng yêu cầu được cấp và click Cho phép
![](/assets/OA/img/uy_quyen_1.jpg)

{/* ![](/assets/OA/img/uy_quyen_1.jpg) */}

- Sao chép access token và sử dụng access token để gọi các OA API
![](/assets/OA/img/tool6.png)

{/* ![](/assets/OA/img/tool6.png) */}

### 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
![](/assets/OA/img/tool7.png)

{/* ![](/assets/OA/img/tool7.png) */}