Tài Liệu API
Các Mẫu Xác Thực Nâng Cao — OAuth 2.0, JWT, Luân Chuyển Khóa
Làm chủ các cơ chế xác thực phức tạp để tích hợp Smart Money API trong môi trường doanh nghiệp. Tìm hiểu các luồng OAuth 2.0, mẫu token JWT, luân chuyển khóa an toàn và triển khai xác thực đa yếu tố.
Đăng ngày 21 tháng 3, 2026
•
18 phút đọc
•
Nâng Cao
Tổng Quan Về Xác Thực
Smart Money API hỗ trợ nhiều phương pháp xác thực được thiết kế để phù hợp với các kiến trúc ứng dụng khác nhau, yêu cầu bảo mật và chính sách tổ chức. Hiểu rõ các mẫu này đảm bảo tích hợp của bạn vừa an toàn vừa hiệu suất cao.
Xác thực trong Smart Money API hoạt động trên ba lớp chính:
- API Keys — Xác thực token bearer đơn giản cho phát triển và tích hợp trực tiếp
- JWT Tokens — Token không trạng thái, được ký mã hóa cho hệ thống phân tán và microservices
- OAuth 2.0 — Khung ủy quyền cho tích hợp bên thứ ba và ứng dụng SaaS
Nguyên Tắc Bảo Mật: Không bao giờ tiết lộ thông tin xác thực trong mã phía client, nhật ký, kiểm soát phiên bản hoặc thông báo lỗi. Thực hiện luân chuyển thông tin đăng nhập theo lịch trình và ngay lập tức khi bị xâm phạm.
Mỗi phương pháp có ưu điểm riêng. API keys hoạt động tốt nhất cho giao tiếp backend-to-backend khi lưu trữ thông tin đăng nhập được kiểm soát. JWT tokens vượt trội trong kiến trúc phân tán khi không có trạng thái chia sẻ. OAuth 2.0 cung cấp quyền truy cập ủy quyền người dùng cho ứng dụng bên thứ ba.
Xác Thực Bằng API Key
API keys là cơ chế xác thực đơn giản nhất — chúng là chuỗi ngẫu nhiên được tạo cho tài khoản của bạn để xác định ứng dụng của bạn với Smart Money API. Mọi yêu cầu phải bao gồm API key của bạn dưới dạng header hoặc tham số truy vấn.
API Key Dựa Trên Header
Cách tiếp cận được khuyến nghị là truyền API key của bạn trong header Authorization bằng cách sử dụng scheme Bearer:
curl -X GET "https://api.smartmoneyapi.com/v1/whales/btc" \
-H "Authorization: Bearer sk_live_1234567890abcdef" \
-H "Accept: application/json"
API Key Tham Số Truy Vấn
Đối với kết nối WebSocket hoặc khi không thể sửa đổi header, hãy truyền API key dưới dạng tham số truy vấn:
ws://localhost:8877/ws?api_key=sk_live_1234567890abcdef
// Thiết lập luồng WebSocket đã xác thực
Đặc Điểm API Key
| Thuộc Tính |
Mô Tả |
| Định Dạng |
Chuỗi hex 128 ký tự có tiền tố sk_test_ hoặc sk_live_ |
| Phạm Vi |
Kế thừa tất cả quyền của tài khoản tạo ra nó |
| Hết Hạn |
Không bao giờ tự động hết hạn; phải luân chuyển thủ công |
| Luân Chuyển |
Tạo key mới, di chuyển lưu lượng, sau đó hủy kích hoạt key cũ |
| Giới Hạn Tốc Độ |
Chia sẻ trên tất cả yêu cầu sử dụng cùng key |
Thực Tiễn Bảo Mật API Key
- Biến Môi Trường — Lưu trữ key trong tệp .env (không commit vào kiểm soát phiên bản) và tải lúc chạy
- Hệ Thống Vault — Sử dụng HashiCorp Vault, AWS Secrets Manager hoặc Azure Key Vault trong môi trường production
- Key Riêng Biệt — Duy trì key test và live riêng biệt; luân chuyển key test thường xuyên
- Phạm Vi Tối Thiểu — Tạo key riêng cho các tích hợp khác nhau khi có thể
- Ghi Nhật Ký Kiểm Tra — Ghi lại tất cả sự kiện tạo và sử dụng API key
Nhận API key của bạn trong 30 giây
Sẵn sàng xây dựng? Lấy API key miễn phí (100 cuộc gọi/ngày, không cần thẻ) và bắt đầu truy cập dữ liệu whale, funding và on-chain trực tiếp.
Nhận API key của bạn →Mẫu Token Bearer
Token Bearer mở rộng khái niệm API key đơn giản bằng cách thêm ngữ cảnh, thời gian hết hạn và cơ chế làm mới. Chúng lý tưởng cho ứng dụng cần quản lý thông tin đăng nhập theo chương trình.
Nhận Token Bearer
Đổi API key và secret của bạn lấy token bearer có hiệu lực trong 24 giờ:
curl -X POST "https://api.smartmoneyapi.com/v1/auth/token" \
-H "Content-Type: application/json" \
-d '{
"api_key": "sk_live_1234567890",
"api_secret": "secret_abc123xyz"
}'
Định Dạng Phản Hồi Token
Điểm cuối trả về token bearer với siêu dữ liệu:
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 86400,
"refresh_token": "refresh_1234567..."
}
Sử Dụng Token Bearer
Bao gồm token trong header Authorization cho tất cả yêu cầu tiếp theo:
curl -X GET "https://api.smartmoneyapi.com/v1/derivatives/funding-heatmap" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Luồng Làm Mới Token
Khi token gần hết hạn, sử dụng refresh token để nhận token mới mà không cần API secret:
curl -X POST "https://api.smartmoneyapi.com/v1/auth/refresh" \
-H "Content-Type: application/json" \
-d '{
"refresh_token": "refresh_1234567..."
}'
Triển Khai OAuth 2.0
OAuth 2.0 cho phép người dùng cấp quyền truy cập vào tài khoản Smart Money API của họ cho ứng dụng mà không cần chia sẻ thông tin đăng nhập. Điều này rất quan trọng cho nền tảng SaaS, tích hợp bên thứ ba và ứng dụng đa tenant.
Luồng Mã Ủy Quyền OAuth 2.0
Luồng tiêu chuẩn cho ứng dụng web:
- Người Dùng Khởi Tạo Đăng Nhập — Người dùng nhấp "Kết nối với Smart Money API"
- Chuyển Hướng Đến Máy Chủ Ủy Quyền — Ứng dụng của bạn chuyển hướng người dùng đến điểm cuối ủy quyền của Smart Money
- Người Dùng Cấp Quyền — Người dùng xem lại phạm vi được yêu cầu và cấp quyền truy cập
- Mã Ủy Quyền Được Trả Về — Người dùng được chuyển hướng trở lại với mã ủy quyền
- Đổi Mã Lấy Token — Backend đổi mã lấy token truy cập (mã không bao giờ tiết lộ cho frontend)
- Lưu Trữ Token — Lưu trữ refresh token một cách an toàn; sử dụng access token để gọi API
Bước 1: Chuyển hướng Người dùng đến Điểm cuối Ủy quyền
// URL để chuyển hướng người dùng
const authUrl = new URL('https://api.smartmoneyapi.com/oauth/authorize');
authUrl.searchParams.append('client_id', 'your_client_id');
authUrl.searchParams.append('redirect_uri', 'https://yourapp.com/callback');
authUrl.searchParams.append('response_type', 'code');
authUrl.searchParams.append('scope', 'whales derivatives onchain');
authUrl.searchParams.append('state', generateRandomState());
window.location.href = authUrl.toString();
Bước 2: Xử lý Callback và Trao đổi Mã
// Backend xử lý route /callback
const code = req.query.code;
const storedState = req.session.state;
const receivedState = req.query.state;
// Xác minh tham số state
if (storedState !== receivedState) {
throw new Error('State mismatch - CSRF attack detected');
}
// Trao đổi mã để lấy token
const tokenResponse = await fetch('https://api.smartmoneyapi.com/oauth/token', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
grant_type: 'authorization_code',
code: code,
client_id: process.env.OAUTH_CLIENT_ID,
client_secret: process.env.OAUTH_CLIENT_SECRET,
redirect_uri: 'https://yourapp.com/callback'
})
});
const tokens = await tokenResponse.json();
// Lưu trữ token một cách an toàn
Phạm vi OAuth
Chỉ yêu cầu các phạm vi mà ứng dụng của bạn cần. Smart Money API định nghĩa các phạm vi sau:
| Phạm vi |
Mô tả |
| whales |
Truy cập theo dõi ví cá voi và số liệu tích lũy |
| derivatives |
Truy cập dữ liệu futures, perpetuals và funding rate |
| onchain |
Truy cập luồng giao dịch và phân tích on-chain |
| alerts |
Tạo và quản lý cảnh báo webhook |
| offline |
Truy cập refresh token để lấy access token mới khi offline |
Quản lý Token JWT
JWT (JSON Web Tokens) cung cấp xác thực không trạng thái—máy chủ không cần lưu trữ dữ liệu phiên. Smart Money API sử dụng RS256 (Chữ ký RSA với SHA-256) để ký token, cho phép xác minh mà không cần liên hệ với API.
Cấu trúc JWT
Token JWT bao gồm ba phần được phân cách bằng dấu chấm:
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEifQ.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFjY3QxMjM0In0.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
// HEADER.PAYLOAD.SIGNATURE
Header JWT
Header xác định thuật toán và loại token:
{
"alg": "RS256",
"typ": "JWT",
"kid": "1"
}
Claims Payload JWT
Payload chứa các claims (tuyên bố về người dùng/ứng dụng):
{
"sub": "acct_1234567890",
"name": "Trading Bot",
"iat": 1703001600,
"exp": 1703088000,
"scopes": ["whales", "derivatives"],
"aud": "https://api.smartmoneyapi.com"
}
Xác minh Chữ ký JWT
Tải xuống khóa công khai của Smart Money và xác minh token trước khi chấp nhận chúng:
const jwt = require('jsonwebtoken');
const fs = require('fs');
// Lấy khóa công khai từ Smart Money API
const publicKey = fs.readFileSync('smartmoney-public.pem');
// Xác minh token
try {
const decoded = jwt.verify(token, publicKey, {
algorithms: ['RS256'],
audience: 'https://api.smartmoneyapi.com',
issuer: 'https://api.smartmoneyapi.com'
});
// Token hợp lệ, sử dụng các claims đã giải mã
} catch (err) {
// Token không hợp lệ hoặc đã hết hạn
}
Chiến lược Luân chuyển Khóa
Luân chuyển khóa thường xuyên là rất quan trọng để duy trì bảo mật. Ngay cả với các biện pháp bảo mật hoàn hảo, hãy giả định rằng khóa có thể bị xâm phạm và triển khai luân chuyển có hệ thống.
Tần suất Luân chuyển
Smart Money khuyến nghị các lịch trình luân chuyển khác nhau dựa trên loại khóa và cách sử dụng:
| Loại Khóa |
Luân chuyển Được Khuyến nghị |
Luân chuyển Tối thiểu |
| Khóa API Thử nghiệm |
Hàng tháng |
Hàng quý |
| Khóa API Sản xuất |
Hàng quý |
Hàng năm |
| Refresh Token OAuth |
Tự động (sau 90 ngày) |
Thủ công (sau 180 ngày) |
| Khóa Tài khoản Dịch vụ |
Nửa năm |
Hàng năm |
Quy trình Luân chuyển Không Gián đoạn
Luân chuyển khóa mà không làm gián đoạn dịch vụ:
- Tạo Khóa Mới — Tạo khóa API mới thông qua bảng điều khiển hoặc API
- Triển khai Khóa Mới — Cập nhật các secret ứng dụng trong môi trường staging, kiểm tra kỹ lưỡng
- Triển khai Dần dần — Triển khai đến 10% máy chủ, theo dõi lỗi
- Triển khai Toàn bộ — Triển khai đến các máy chủ còn lại
- Kiểm tra Lưu lượng — Xác nhận tất cả các yêu cầu sử dụng khóa mới
- Vô hiệu hóa Khóa Cũ — Đánh dấu khóa cũ là không hoạt động nhưng không xóa ngay lập tức
- Xóa Khóa Cũ — Sau 48 giờ không có lỗi, xóa vĩnh viễn
Xoay Khóa Khẩn cấp
Nếu bạn nghi ngờ một khóa bị xâm phạm:
// Hành động ngay lập tức: Vô hiệu hóa khóa bị xâm phạm
curl -X POST "https://api.smartmoneyapi.com/v1/keys/sk_live_xxx/revoke" \
-H "Authorization: Bearer token"
// Tạo khóa thay thế ngay lập tức
curl -X POST "https://api.smartmoneyapi.com/v1/keys" \
-H "Content-Type: application/json" \
-d '{
"name": "Khóa Thay thế Khẩn cấp"
}'
Xoay Khóa Tự động trong Kubernetes
Sử dụng Kubernetes Secrets và các toán tử để xoay khóa tự động:
apiVersion: batch/v1
kind: CronJob
metadata:
name: api-key-rotator
spec:
schedule: "0 0 * * 0" # Hàng tuần vào Chủ nhật
jobTemplate:
spec:
template:
spec:
containers:
- name: rotator
image: smartmoney-key-rotator:latest
Xác thực Đa yếu tố (MFA)
Đối với các tài khoản truy cập dữ liệu sản xuất, MFA cung cấp một lớp bảo mật bổ sung bằng cách yêu cầu một yếu tố thứ hai ngoài chỉ thông tin đăng nhập.
Các Phương thức MFA được Hỗ trợ
- TOTP (Mật khẩu Một lần dựa trên Thời gian) — Các ứng dụng như Google Authenticator, Authy
- WebAuthn/FIDO2 — Khóa bảo mật phần cứng, sinh trắc học
- Mã Một lần qua SMS — Ít bảo mật hơn nhưng được hỗ trợ rộng rãi
- Xác nhận qua Email — Mã xác nhận được gửi đến email đã đăng ký
Kích hoạt TOTP để Truy cập Tài khoản
// Bước 1: Yêu cầu thiết lập MFA
curl -X POST "https://api.smartmoneyapi.com/v1/account/mfa/enable" \
-H "Authorization: Bearer token"
// Phản hồi bao gồm URL mã QR
{
"qr_code_url": "https://...",
"secret": "JBSWY3DPEBLW64TMMQ...",
"backup_codes": ["12345678", ...]
}
MFA Trong Các Hoạt động API
Một số hoạt động có thể yêu cầu xác nhận MFA ngay cả sau khi xác thực:
// Thử thực hiện thao tác nhạy cảm (xoay khóa)
curl -X POST "https://api.smartmoneyapi.com/v1/keys/rotate" \
-H "Authorization: Bearer token" \
-H "X-MFA-Token: mfa_challenge_abc123"
// Phản hồi: Yêu cầu MFA
{
"error": "mfa_required",
"mfa_token": "mfa_xyz789"
}
// Thử lại với mã TOTP
curl -X POST "https://api.smartmoneyapi.com/v1/keys/rotate" \
-H "Authorization: Bearer token" \
-H "X-MFA-Code: 123456"
Các Thực tiễn Bảo mật Tốt nhất
Xác thực chỉ mạnh bằng cách triển khai của nó. Hãy tuân theo các thực tiễn này để duy trì bảo mật:
Quản lý Bí mật
- Không bao giờ cam kết bí mật vào kiểm soát phiên bản — Sử dụng tệp .env với .gitignore
- Sử dụng biến môi trường — Tải từ các hệ thống quản lý bí mật an toàn
- Quét kho lưu trữ — Sử dụng các công cụ như TruffleHog, detect-secrets để tìm các khóa bị lộ
- Kiểm tra nhật ký truy cập — Theo dõi ai đã truy cập bí mật và khi nào
Bảo mật Truyền tải
- Luôn sử dụng HTTPS — Không bao giờ gửi thông tin đăng nhập qua các kết nối không được mã hóa
- Xác minh chứng chỉ SSL — Không tắt xác thực chứng chỉ trong môi trường sản xuất
- Sử dụng ghim chứng chỉ — Đối với ứng dụng di động, ngăn chặn các cuộc tấn công MITM
- Áp dụng TLS 1.2+ — Tắt các giao thức cũ hơn
Xử lý Thông tin Đăng nhập
- Băm bí mật — Lưu trữ các băm bcrypt hoặc Argon2, không bao giờ lưu trữ dưới dạng văn bản thuần túy
- Giảm thiểu thời gian tồn tại — Giữ thông tin đăng nhập trong bộ nhớ chỉ trong thời gian cần thiết
- Xóa dữ liệu nhạy cảm — Ghi đè rõ ràng thông tin đăng nhập sau khi sử dụng
- Sử dụng các thư viện bảo mật — Không tự triển khai mã hóa
Ghi nhật ký và Giám sát
- Không bao giờ ghi nhật ký thông tin đăng nhập — Che giấu các khóa trong nhật ký, sử dụng mặt nạ nhật ký
- Ghi nhật ký các sự kiện xác thực — Theo dõi các lần đăng nhập thành công và thất bại
- Giám sát các bất thường — Cảnh báo về các mẫu truy cập bất thường
- Kiểm tra việc sử dụng khóa — Theo dõi các khóa đã truy cập dữ liệu nào
Các Mẫu Xác thực Doanh nghiệp
Các tổ chức lớn thường yêu cầu các biện pháp kiểm soát bảo mật bổ sung và khả năng tuân thủ.
Tích hợp SAML 2.0
Đối với khách hàng doanh nghiệp, Smart Money API hỗ trợ tích hợp SAML 2.0 với nhà cung cấp danh tính của tổ chức bạn (Okta, Azure AD, v.v.):
- Đăng nhập Đơn (SSO) — Người dùng xác thực thông qua IdP của công ty bạn
- Cung cấp tự động — Tạo/vô hiệu hóa tài khoản dựa trên thành viên nhóm
- Thực thi — Yêu cầu SAML cho tất cả quyền truy cập người dùng
Danh sách Trắng IP
Hạn chế quyền truy cập API vào các địa chỉ IP hoặc phạm vi CIDR cụ thể:
// Thêm IP vào whitelist
curl -X POST "https://api.smartmoneyapi.com/v1/account/ip-whitelist" \
-H "Authorization: Bearer token" \
-d '{
"cidr": "203.0.113.0/24",
"description": "Production servers"
}'
Ghi nhật ký kiểm toán và tuân thủ
Các gói doanh nghiệp bao gồm nhật ký kiểm toán toàn diện để tuân thủ:
| Sự kiện |
Dữ liệu được ghi nhật ký |
| Xác thực |
Người dùng, thời gian, thành công/thất bại, IP, trạng thái MFA |
| Thao tác với khóa |
ID khóa, hành động, người khởi tạo, thời gian |
| Thay đổi tài khoản |
Điều gì đã thay đổi, ai thay đổi, thời gian, giá trị trước/sau |
| Truy cập dữ liệu |
Người dùng, điểm cuối, phạm vi, thời gian, số lượng bản ghi |
Khắc phục sự cố xác thực
Lỗi API Key không hợp lệ
Vấn đề: Nhận được "401 Unauthorized - Invalid API Key"
Giải pháp:
- Kiểm tra định dạng khóa (nên bắt đầu bằng sk_test_ hoặc sk_live_)
- Kiểm tra khoảng trắng đầu/cuối trong khóa
- Xác nhận khóa chưa bị vô hiệu hóa hoặc xoay
- Xác nhận bạn đang sử dụng môi trường đúng (khóa test cho test, live cho production)
- Kiểm tra quyền của API key khớp với yêu cầu của điểm cuối
Lỗi Token hết hạn
Vấn đề: Bearer token hết hạn, yêu cầu thất bại
Giải pháp:
- Sử dụng refresh token để lấy access token mới
- Triển khai tự động làm mới token 5 phút trước khi hết hạn
- Lưu trữ refresh token an toàn (không trong localStorage cho SPAs)
- Xử lý phản hồi 401 bằng cách thử luồng refresh token
Lỗi CORS/Preflight
Vấn đề: Trình duyệt chặn yêu cầu với lỗi CORS
Giải pháp:
- Các cuộc gọi API từ trình duyệt phải đến từ các nguồn được whitelist
- Thêm tên miền của bạn qua bảng điều khiển: Settings → CORS Origins
- Trình duyệt tự động gửi yêu cầu OPTIONS preflight
- Để phát triển, sử dụng localhost:3000 hoặc tương tự
Thử thách MFA không hoàn thành
Vấn đề: Các thao tác yêu cầu MFA thất bại ngay cả với mã đúng
Giải pháp:
- Đảm bảo đồng hồ máy chủ được đồng bộ hóa (TOTP phụ thuộc vào thời gian)
- Mã chỉ hợp lệ trong 30 giây, tạo mã mới
- Sử dụng mã dự phòng nếu ứng dụng xác thực không khả dụng
- Khôi phục tài khoản qua email đã đăng ký
Triển khai xác thực an toàn ngay hôm nay
Smart Money API hỗ trợ xác thực cấp doanh nghiệp với OAuth 2.0, JWT, MFA và tích hợp SAML. Bảo mật tích hợp API của bạn với các phương pháp tốt nhất trong ngành.
Xem các gói doanh nghiệp
Cần SAML, IP whitelisting hoặc hỗ trợ chuyên dụng? Liên hệ với đội ngũ bán hàng của chúng tôi.