Access Token

Nội dung Markdown đầy đủ của trang tài liệu.

# Access Token

Access token cho phép ứng dụng gọi API trong phạm vi người dùng đã đồng ý. Token OAuth Pay2S là chuỗi ngẫu nhiên **không phải JWT**; không giải mã để suy ra người dùng, thời hạn hay quyền.

## Các loại mã và thời hạn

| Loại | Dùng để làm gì | Thời hạn tối đa |
|---|---|---|
| Authorization code | Đổi lấy token một lần | 120 giây |
| Access token | Gọi API với Bearer | 15 phút |
| Refresh token | Đổi cặp token mới | 30 ngày |
| Kết nối đã cấp quyền | Giới hạn phiên tích hợp | 90 ngày |

Kết nối bị thu hồi hoặc ứng dụng bị khóa sẽ mất hiệu lực sớm hơn. Dùng `expires_in` từ response để lên lịch làm mới; không dựa vào việc phân tích chuỗi token.

## Gửi token trong request

```bash
curl 'https://api.pay2s.vn/api/v1/oauth/me' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

[API người dùng](/docs/oauth/me/) yêu cầu scope `profile:read`. Ngân hàng, giao dịch và webhook yêu cầu các [scopes](/docs/oauth/scopes/) riêng cùng ngân hàng được khách chọn.

## Đổi mã và làm mới

- [Đổi code lấy token](/docs/oauth/token/): thực hiện từ backend ngay khi nhận callback hợp lệ.
- [Làm mới token](/docs/oauth/refresh/): mỗi lần thành công cấp **cả access token và refresh token mới**. Lưu đồng thời và thay cặp cũ.
- [Thu hồi kết nối](/docs/oauth/revoke/): dừng kết nối chứa token, gồm webhook liên quan.

Chỉ cho một tác vụ refresh chạy trên mỗi kết nối tại một thời điểm. Refresh token dùng một lần; dùng lại token đã đổi có thể làm kết nối bị thu hồi. Nếu timeout và không biết request đã thành công chưa, không retry mù bằng refresh token cũ.

## Lưu trữ và xử lý lỗi

Giữ token tại backend, tách theo tài khoản và kết nối; không đưa vào URL, localStorage hoặc log. `invalid_token` có thể do hết hạn hoặc bị thu hồi. Kiểm tra refresh còn khả dụng; nếu kết nối không còn hợp lệ, yêu cầu người dùng bắt đầu [luồng cấp quyền mới](/docs/oauth/authentication-flow/). Lỗi quyền, ngân hàng hoặc gói dịch vụ không được giải quyết bằng cách refresh liên tục.

[Tra cứu lỗi và giới hạn →](/docs/oauth/errors/)