> ## Documentation Index
> Fetch the complete documentation index at: https://hoalulab.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Cách lấy API Key / Access Token

> Tạo, quản lý, và bảo mật API credentials

## 1. Tạo API Key

### Các bước thực hiện:

1. **Đăng nhập** vào [Developer Portal](https://developers.ssi.com.vn) bằng tài khoản SSI
2. Vào **Bảng điều khiển → Quản lý API Key → Tạo Key mới**
3. Đặt tên cho API Key (ví dụ: "Trading Bot Production")
4. Click **Tạo** → **Lưu ngay API Key và API Secret**

> ⚠️ **Quan trọng**: API Secret chỉ hiển thị **MỘT LẦN DUY NHẤT**. Nếu mất, bạn cần xem lại trong chi tiết API Key.

## 2. Quy trình xác thực API

### Bước 1: Lấy Access Token

Gọi endpoint `/api/v3/auth/token` với API Key và Secret:

```bash theme={null}
POST /api/v3/auth/token
Headers:
  Content-Type: application/json
Body:
{
  "apiKey": "YOUR_API_KEY",
  "apiSecret": "YOUR_API_SECRET"
}
```

### Bước 2: Sử dụng Access Token

Thêm token vào header `Authorization` cho mọi API call:

```bash theme={null}
Authorization: Bearer YOUR_ACCESS_TOKEN
```

### Bước 3: Làm mới Token

Khi access token hết hạn, dùng refresh token để lấy token mới.

## 3. Xác thực 2FA cho giao dịch

Để đặt/sửa/hủy lệnh, cần có **OTP** hoặc **transactionId** khi gọi `/api/v3/auth/token`:

| Tình huống | Phương thức |
| - | - |
| **OTP SMS/Email** | Gọi `requestOtp` → nhận OTP → truyền vào tham số `otp` |
| **SmartOTP (iBoard)** | Mở app iBoard → lấy mã hiển thị → truyền vào `otp` (không cần gọi requestOtp) |
| **Mobile Approval** | Gọi API nhận `transactionId` → phê duyệt trên app iBoard trong **30 giây** |

> 💡 **Mẹo**: Để tự động hóa, nên dùng luồng **Mobile Approval** để không phải nhập OTP thủ công mỗi ngày.

## 4. Quản lý API Key

### Xem chi tiết Key

Đăng nhập Developer Portal → Bảng điều khiển → Quản lý API Key → Chọn key → Chi tiết

### Xoay vòng (Rotate) Key

1. Tạo API Key mới trên Developer Portal
2. Cập nhật key mới vào ứng dụng
3. Test kỹ với key mới
4. Xóa key cũ

### Xóa Key

Xóa ngay khi:

* Key bị lộ ra ngoài
* Không còn sử dụng
* Cần thay thế bằng key mới

## 5. Bảo mật - Nên và Không nên

| ✅ NÊN | ❌ KHÔNG NÊN |
| - | - |
| Lưu key trong environment variables hoặc secret manager | Commit key vào Git/GitHub |
| Sử dụng HTTPS cho mọi request | Hardcode key trong source code |
| Rotate key định kỳ | Share key qua email/chat |
| Tạo key riêng cho từng ứng dụng | Dùng key Production cho testing |
| Monitor API usage để phát hiện bất thường | Dùng chung key giữa nhiều ứng dụng |

## 6. Ví dụ trích xuất thông tin từ response

Khi gọi `/api/v3/auth/token` thành công, response sẽ có dạng:

```json theme={null}
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}
```

**Trích xuất các giá trị:**

* `accessToken`: Dùng cho header Authorization
* `refreshToken`: Dùng để làm mới token khi hết hạn
* `expiresIn`: Thời gian sống của token (giây)

## Bước tiếp theo

Sau khi có API Key và Access Token, bạn có thể bắt đầu gọi các API khác của SSI.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.