Xác thực

​

Xác thực ứng dụng

Trong giao tiếp giữa ứng dụng của Người dùng và hệ thống DNSE, việc xác minh danh tính và bảo vệ tính toàn vẹn của dữ liệu là yêu cầu bắt buộc. Mọi RESTful API gửi đến DNSE đều bắt buộc kèm theo 3 thông tin cốt lõi trong Headers: X-Api-Key, X-Signature và Date (hoặc tên Header cấu hình riêng).

​

API Key

• API Key là khóa định danh duy nhất được cấp cho từng tài khoản khi đăng ký sử dụng LightSpeed API.
• Trong mỗi request, API Key là thành phần bắt buộc để nhận diện ứng dụng và áp dụng cơ chế phân quyền, giới hạn truy cập.
• API Key cần được quản lý cẩn trọng và tránh chia sẻ công khai. Người dùng có thể chủ động tạo mới hoặc thu hồi API Key trong trường hợp nghi ngờ lộ thông tin hoặc không còn nhu cầu sử dụng.
• Trường hợp bị rò rỉ, các yêu cầu trái phép sẽ không được chấp nhận nếu không có Signature hợp lệ đi kèm.

​

Signature (Chữ ký số)

• Hệ thống OpenAPI sử dụng chuẩn HTTP Signature để chứng thực tính toàn vẹn của dữ liệu trên đường truyền. Mỗi Request hợp lệ gửi lên hệ thống bắt buộc phải đính kèm Header X-Signature. Cấu trúc Signature: HMAC‑SHA256 (API Secret, method + path + date header + nonce) → Base64 URL‑encode

:::warning[Lưu ý quan trọng]

• Giới hạn thời gian: Để chống replay attack, giá trị Header Date phải chính xác và không được lệch quá ±1 phút so với giờ chuẩn của hệ thống DNSE.
• Mỗi request phải có Date và Nonce mới — Signature gắn liền với giá trị Date và nonce tại thời điểm tạo. Không được tái sử dụng Signature cũ.
• Sai thứ tự dòng trong Signing String → Signature sai dẫn đến Request bị từ chối ngay lập tức.
• Kiểm tra kỹ URL-encode, chỉ mã hóa +, /, = từ chuỗi Base64 gốc.
• Để không cần tự implement thuật toán và giảm thiểu lỗi, DNSE cung cấp SDK tự động sinh Signature cho mỗi request. Tham khảo tại GitHub DNSE OpenAPI

:::

​

Lỗi có thể gặp

Nếu thông tin xác thực không hợp lệ (ví dụ sai Signature hoặc Date), API sẽ trả về lỗi:

{
  "status": "error",
  "code": "OA-400",
  "message": "Authorization field missing, malformed or invalid"
}

Nguyên nhân thường gặp:

• Signature được tạo không chính xác (sai thuật toán, sai chuỗi ký hoặc sử dụng sai API Secret).
• Giá trị Date không đúng định dạng hoặc không khớp với giá trị dùng để tạo Signature.
• Authorization header bị thiếu hoặc sai định dạng.

Cách khắc phục:

• Kiểm tra lại chuỗi dữ liệu dùng để tạo Signature.
• Đảm bảo Signature được ký bằng đúng API Secret.
• Đảm bảo giá trị Date trong header giống hoàn toàn với giá trị đã sử dụng khi tạo Signature.
• Kiểm tra định dạng và nội dung của header Authorization.

---

​

Xác thực giao dịch

Nếu API Key đóng vai trò là lớp bảo mật thứ nhất, thì Trading Token là lớp bảo mật thứ 2 đối với giao dịch đặt lệnh theo cơ chế 2FA – Two Factor Authentication.

Trading Token là mã có thời hạn 8 tiếng, được cung cấp sau khi người dùng hoàn tất xác thực OTP, và là thông tin bắt buộc phải được truyền kèm trong các API đặt lệnh. Trong thời gian token còn hiệu lực, người dùng có thể liên tục đặt lệnh mà không cần cấu hình lại OTP cho từng Request.

​

Phương thức OTP

OpenAPI hiện hỗ trợ hai phương thức Email OTP hoặc Smart OTP để xác thực và tạo Trading Token. Tại mỗi thời điểm, chỉ một phương thức OTP duy nhất được hoạt động.

​

Email OTP

• Mã OTP được gửi về địa chỉ email mà người dùng đã đăng ký, có hiệu lực trong 2 phút.
• Ưu điểm:
  • Quản lý linh hoạt, có thể tự động hóa trong quy trình xác thực, mang lại trải nghiệm liền mạch cho người dùng khi xây dựng hệ thống giao dịch qua OpenAPI.
• Hạn chế:
  • Thời gian nhận email phụ thuộc vào bên thứ 3.

​

Smart OTP

• Mã OTP được lấy trực tiếp trên ứng dụng DNSE đã đăng ký SmartOTP, có hiệu lực trong 30 giây.
• Ưu điểm:
  • Mã luôn có sẵn trên ứng dụng và chỉ sinh trên thiết bị đã đăng ký.
  • Độ bảo mật cao do, giảm thiểu nguy cơ giả mạo hoặc truy cập trái phép.
• Hạn chế:
  • Người dùng cần thao tác thủ công vào ứng dụng để lấy mã khi cần thực hiện xác thực.