OAuth 2.0 API Documentation

Hướng dẫn tích hợp OAuth 2.0 để truy cập thông tin người dùng một cách an toàn

📋 Tổng quan

Hệ thống OAuth 2.0 cho phép các ứng dụng bên thứ ba truy cập thông tin người dùng một cách an toàn mà không cần chia sẻ mật khẩu.

✅ Yêu cầu

Tài khoản đã xác thực eKYC
Tạo OAuth App tại: https://app.opencard.vn/create-app

🔄 OAuth Flow

1. Authorization Request

Chuyển hướng người dùng đến:

http

GET https://app.opencard.vn/connect/authorize?app_id={APP_ID}&redirect_uri={REDIRECT_URI}&state={STATE}&response_type=code

Parameters:

app_id (required): App ID của bạn
redirect_uri (required): URL callback đã đăng ký
state (optional): Random string để chống CSRF
response_type (required): Phải là "code"

Response:

Sau khi user authorize, sẽ redirect về:

text

{REDIRECT_URI}?code={AUTHORIZATION_CODE}&state={STATE}

2. Exchange Code for Token

http

POST https://app.opencard.vn/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code={AUTHORIZATION_CODE}
&app_id={APP_ID}
&app_secret={APP_SECRET}
&redirect_uri={REDIRECT_URI}

Response:

json

{
  "access_token": "abc123...",
  "token_type": "Bearer",
  "expires_in": 2592000,
  "refresh_token": "xyz789...",
  "scope": "uid,full_name,avatar,email"
}

3. Get User Info

http

GET https://app.opencard.vn/connect/userinfo
Authorization: Bearer {ACCESS_TOKEN}

Hoặc:

http

GET https://app.opencard.vn/connect/userinfo?access_token={ACCESS_TOKEN}

Response:

json

{
  "uid": "830153242552966081",
  "username": "opencarduser",
  "full_name": "User Open Card",
  "avatar": "https://cdn.opencard.vn/avatar.jpg",
  "email": "demo@opencard.vn",
  "phone": "0123456789",
  "ekyc_status": "approved"
}

* Các trường trả về phụ thuộc vào scopes đã được cấp.

4. Refresh Token

http

POST https://app.opencard.vn/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token={REFRESH_TOKEN}
&app_id={APP_ID}
&app_secret={APP_SECRET}

Response:

json

{
  "access_token": "new_token...",
  "token_type": "Bearer",
  "expires_in": 2592000,
  "refresh_token": "xyz789...",
  "scope": "uid,full_name,avatar,email"
}

🔐 Scopes (Quyền truy cập)

Scope	Mô tả
`uid`	UID người dùng
`full_name`	Họ và tên
`avatar`	Ảnh đại diện
`email`	Địa chỉ email
`phone`	Số điện thoại
`ekyc_status`	Trạng thái xác minh eKYC

⏱️ Token Expiration

Token Type	Thời gian hết hạn
Authorization Code	5 phút
Access Token	30 ngày
Refresh Token	90 ngày

❌ Error Responses

json

{
  "error": "invalid_request",
  "error_description": "Missing required parameters"
}

Error Codes:

invalid_request: Thiếu hoặc sai parameters
invalid_client: App credentials không hợp lệ
invalid_grant: Authorization code hoặc refresh token không hợp lệ
invalid_token: Access token không hợp lệ hoặc đã hết hạn
unsupported_grant_type: Grant type không được hỗ trợ
access_denied: User từ chối cấp quyền

💻 Example Code (PHP)

php

<?php
// Step 1: Redirect to authorization
$auth_url = 'https://app.opencard.vn/connect/authorize?' . http_build_query([
    'app_id' => 'your_app_id',
    'redirect_uri' => 'https://yourapp.com/callback',
    'state' => bin2hex(random_bytes(16)),
    'response_type' => 'code'
]);
header('Location: ' . $auth_url);

// Step 2: Handle callback and exchange code
$code = $_GET['code'];
$ch = curl_init('https://app.opencard.vn/connect/token');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    'grant_type' => 'authorization_code',
    'code' => $code,
    'app_id' => 'your_app_id',
    'app_secret' => 'your_app_secret',
    'redirect_uri' => 'https://yourapp.com/callback'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
$access_token = $response['access_token'];

// Step 3: Get user info
$ch = curl_init('https://app.opencard.vn/connect/userinfo');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $access_token
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$user_info = json_decode(curl_exec($ch), true);

print_r($user_info);
?>

🔒 Security Best Practices

Luôn sử dụng HTTPS cho tất cả OAuth endpoints
Validate redirect_uri - Chỉ cho phép redirect về URIs đã đăng ký
Sử dụng state parameter để chống CSRF attacks
Bảo mật App Secret - Không bao giờ expose trong client-side code
Implement rate limiting để chống brute force
Log tất cả OAuth activities để audit
Revoke tokens khi không còn sử dụng

⚡ Rate Limits

Endpoint	Giới hạn
Authorization requests	10 requests/phút/IP
Token requests	20 requests/phút/app
UserInfo requests	100 requests/phút/token

💬 Support

Nếu có vấn đề, vui lòng liên hệ:

📧 Email: support@opencard.vn
📞 Hotline: 0386 455 431

Sẵn sàng tích hợp OAuth?

Tạo OAuth App ngay để bắt đầu tích hợp

Tạo OAuth App