Chuyển tới nội dung chính

Lấy access token

Để bảo vệ API tốt hơn, V-App áp dụng cơ chế access token. Khi bạn gọi các API, access token sẽ đóng vai trò xác thực danh tính người gọi và kiểm soát quyền truy cập. Nhờ đó, V-App biết được ai đang truy cập dữ liệu và tài nguyên ứng dụng.

Access token hoạt động như một "chìa khóa" bảo mật liên kết với tài khoản và quyền hạn của bên gọi đến hệ thống Open API của V-App. Điều này giúp đảm bảo các thao tác đọc/ghi dữ liệu được thực hiện an toàn và đúng thẩm quyền.

Quy trình lấy access token​

Quy trình cấp và sử dụng access token sẽ diễn ra như sau:

  1. Mini App sử dụng JSAPI getAuthCode để yêu cầu mã ủy quyền (authCode).
  2. Mini App nhận được authCode từ ứng dụng.
  3. Mini App gửi authCode vừa nhận được lên máy chủ của Mini App.
  4. Máy chủ của Mini App gọi OpenAPI /oauth2/token/exchange để đổi lấy access token.
  5. Máy chủ của nền tảng xác thực và trả về access token.
  6. Máy chủ của Mini App Backend sử dụng access token và thực hiện các nghiệp vụ mong muốn (ví dụ dùng token đọc thông tin user và lưu ở DB của Mini App Backend và mapping với user của Mini App), sau đó trả về kết quả lại cho Mini App.

Lưu ý: Để xin quyền truy cập các thông tin khác nhau, hãy chỉ định scope phù hợp trong tham số scopes khi gọi getAuthCode.

Lấy Authcode​

Bạn có thể lấy quyền ủy quyền của người dùng bằng cách gọi JSAPI getAuthCode và nhận về authCode trong callback thành công. Ví dụ:

import apis from '@v-miniapp/apis'

apis.getAuthCode({
  scopes: ['profile phone email'],
  success: res => {
    apis.alert({
      content: res.authCode,
    })
  },
  fail: res => {
    console.log(res.authErrorScopes)
  },
})

Lấy access token​

Lưu ý

Access token ỏ đây là User Token, là token được một user cụ thể cho phép truy cập vào tài nguyên cụ thể (scopes), mỗi user sẽ cấp access token riêng biệt.

Exchange Code for Tokens​

Bạn cần lấy authCode của người dùng. Sau đó, bạn sử dụng authCode này để gọi API /oauth2/token/exchange nhằm đổi lấy access token (user token).

Endpoint: POST /oauth2/token/exchange

Request Body

{
  "client_id": "{your-client-id}",
  "client_secret": "{your-client-secret}",
  "auth_code": "{auth-code}"
}

Response thành công:

{
  "code": 0,
  "message": "Success",
  "data": {
    "access_token": "{access_token}",
    "refresh_token": "{refresh_token}",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "profile phone email"
  }
}

Refresh Access Token​

Access token có thời hạn sử dụng giới hạn (thường là 1 giờ). Khi token hết hạn, bạn có thể sử dụng làm mới token để lấy access token mới mà không cần người dùng ủy quyền lại.

Endpoint: POST /oauth2/token/refresh

Request Body:

{
  "client_id": "miniapp_client_123",
  "client_secret": "miniapp_secret_456",
  "refresh_token": "refresh_token_def456"
}

Response thành công:

{
  "code": 0,
  "message": "Success",
  "data": {
    "access_token": "ACCESS_TOKEN",
    "refresh_token": "REFRESH_TOKEN",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "profile phone email"
  }
}

Lưu ý quan trọng:

  • Lưu trữ refresh_token một cách bảo mật
  • Refresh token có thời hạn dài hơn access token (thường là 30 ngày)
  • Khi refresh token thành công, bạn sẽ nhận được cả access token mới và refresh token mới
  • Nên implement cơ chế tự động refresh token khi API trả về lỗi 401 (Unauthorized)

Truy cập Open API​

Sau khi đã lấy được access token, developer có thể tiếp tục sử dụng token này để gọi các API yêu cầu xác thực khác. Lưu ý kiểm tra phạm vi quyền hạn (scope) và thời hạn hiệu lực của access token để đảm bảo truy cập hợp lệ.

Tham khảo thêm:

Câu hỏi thường gặp (FAQs)​

1. Tại sao developer nên sử dụng API getAuthCode?​

Tất cả các thao tác đọc/ghi thông tin người dùng trên nền tảng Mini App đều chỉ thực hiện được sau khi có sự đồng ý của người dùng. Việc ủy quyền này dựa trên chuẩn OAuth2.0, đảm bảo an toàn và minh bạch. Thông qua cơ chế này, developer có thể lấy được thông tin người dùng một cách hợp lệ.

2. Vì sao không được phép xin quyền truy cập người dùng ngay ở màn hình đầu tiên của mini app?​

Để đảm bảo trải nghiệm người dùng tốt hơn, việc xin quyền truy cập (ủy quyền) không nên thực hiện ngay khi mở mini app. Thay vào đó, hãy hướng dẫn người dùng cấp quyền sau khi họ đã hiểu rõ về nội dung và mục đích sử dụng của mini app. Chúng tôi khuyến nghị bạn tích hợp bước xin quyền vào quy trình nghiệp vụ của ứng dụng.

3. Có thể lấy userId thông qua API ủy quyền người dùng không?​

Không, userId chỉ có thể lấy được bằng cách gọi các API liên quan ở phía backend/server.