Steam Auth API - Tài Liệu Hướng Dẫn

1. Giới Thiệu

Steam Auth API cho phép bạn:

• Tạo token để lấy mã xác thực Steam Guard
• Import file maFile vào hệ thống
• Setup authenticator cho tài khoản Steam mới
• Quản lý token với giới hạn số lần dùng và thời gian

2. API Key

Tất cả API endpoints đều yêu cầu API Key trong header.

Lấy API Key

Đăng nhập và tạo API Key của bạn:

Đăng Nhập / Đăng Ký để Lấy API Key

Chưa có tài khoản? Đăng ký miễn phí chỉ mất 1 phút!

Sử dụng API Key

Thêm API Key vào header X-API-Key của mọi request:

X-API-Key: YOUR_API_KEY

Ví dụ với cURL:

curl -X GET "http://localhost:5179/api/token/code?token=ABC123" \
  -H "X-API-Key: YOUR_API_KEY"

3. Endpoints Chính

3.1. Lấy Mã Steam Guard

GET /api/token/code?token=YOUR_TOKEN

Lấy mã xác thực Steam Guard bằng token.

Request:

GET /api/token/code?token=ABC123
X-API-Key: YOUR_API_KEY

Response:

{
  "code": "87MYB",
  "accountName": "username",
  "usageRemaining": 99,
  "expiresAt": "2025-10-20T05:14:18Z",
  "timestamp": "2025-10-20T04:45:30Z"
}

3.2. Import maFile

POST /api/token/import

Import file maFile vào hệ thống để tạo token.

Request:

POST /api/token/import
X-API-Key: YOUR_API_KEY
Content-Type: multipart/form-data

file: [FILE_DATA]

Response:

{
  "accountId": "abc123",
  "accountName": "username",
  "ownerToken": "OWNERTOKEN123",
  "encrypted": true,
  "message": "Import thành công!"
}

3.3. Tạo Token

POST /api/token/create

Tạo token để lấy mã với giới hạn số lần dùng.

Request:

POST /api/token/create
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "accountId": "abc123",
  "maxUsage": 100,
  "expiryMinutes": 60
}

Parameters:

Tên	Kiểu	Bắt buộc	Mô tả
accountId	string	Có	ID của account từ import
maxUsage	number	Không	Số lần dùng tối đa (mặc định: không giới hạn)
expiryMinutes	number	Không	Thời gian hết hạn (phút, mặc định: không giới hạn)

Response:

{
  "token": "XYZ789ABC123",
  "accountName": "username",
  "maxUsage": 100,
  "expiresAt": "2025-10-20T06:00:00Z",
  "createdAt": "2025-10-20T05:00:00Z"
}

4. Setup Account Mới (Tạo maFile)

Tạo maFile mới cho tài khoản Steam chưa có authenticator.

4.1. Bắt Đầu Session

POST /api/setup/login

Đăng nhập vào Steam để bắt đầu quá trình setup.

Request:

POST /api/setup/login
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "username": "your_steam_username",
  "password": "your_steam_password"
}

Response:

{
  "sessionId": "abc123",
  "status": "waiting",
  "message": "Đang chờ xác thực...",
  "requiresEmailCode": true
}

4.2. Xác Thực Email (nếu cần)

POST /api/setup/verify-email

Nhập mã xác thực từ email Steam.

Request:

POST /api/setup/verify-email
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "sessionId": "abc123",
  "emailCode": "AB123"
}

4.3. Thêm Authenticator

POST /api/setup/add-authenticator

Bắt đầu thêm Steam Mobile Authenticator.

Response:

{
  "status": "awaiting_sms",
  "message": "Kiểm tra EMAIL (tiêu đề: 'add an authenticator') để lấy mã",
  "codeSource": "email_or_sms",
  "revocationCode": "R12345"
}

4.4. Hoàn Thành

POST /api/setup/finalize

Nhập mã từ email/SMS để hoàn tất.

Request:

POST /api/setup/finalize
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "sessionId": "abc123",
  "smsCode": "GQP7D"
}

Response:

{
  "status": "success",
  "accountName": "username",
  "revocationCode": "R12345",
  "downloadToken": "xyz789",
  "downloadUrl": "/api/setup/download?token=xyz789",
  "expiresIn": "10 phút"
}

4.5. Tải maFile

GET /api/setup/download?token=DOWNLOAD_TOKEN

Tải file maFile vừa tạo (token hết hạn sau 10 phút).

5. Quy Trình Sử Dụng

Bước 1: Import maFile

1. Chuẩn bị file maFile của bạn
2. Gọi POST /api/token/import
3. Lưu accountId và ownerToken

Bước 2: Tạo Token

1. Sử dụng accountId từ bước 1
2. Gọi POST /api/token/create
3. Nhận token để lấy mã

Bước 3: Lấy Mã

1. Sử dụng token từ bước 2
2. Gọi GET /api/token/code?token=YOUR_TOKEN
3. Nhận mã Steam Guard 5 ký tự

6. Ví Dụ Code

JavaScript / Fetch

const API_BASE = 'http://localhost:5179';
const API_KEY = 'YOUR_API_KEY';

// Lấy mã
async function getCode(token) {
  const response = await fetch(
    `${API_BASE}/api/token/code?token=${token}`,
    {
      headers: { 'X-API-Key': API_KEY }
    }
  );
  
  const data = await response.json();
  console.log('Mã:', data.code);
  return data.code;
}

// Sử dụng
const code = await getCode('YOUR_TOKEN_HERE');

cURL

curl -X GET "http://localhost:5179/api/token/code?token=YOUR_TOKEN" \
  -H "X-API-Key: YOUR_API_KEY"

Python

import requests

API_BASE = 'http://localhost:5179'
API_KEY = 'YOUR_API_KEY'

def get_code(token):
    response = requests.get(
        f'{API_BASE}/api/token/code',
        params={'token': token},
        headers={'X-API-Key': API_KEY}
    )
    return response.json()['code']

# Sử dụng
code = get_code('YOUR_TOKEN_HERE')
print(f'Mã: {code}')

PHP

<?php
$apiBase = 'http://localhost:5179';
$apiKey = 'YOUR_API_KEY';
$token = 'YOUR_TOKEN_HERE';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$apiBase/api/token/code?token=$token");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: $apiKey"
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
$code = $data['code'];

echo "Mã: $code";
?>

7. Lỗi Thường Gặp

401 Unauthorized

API Key không đúng hoặc thiếu header X-API-Key.

Giải pháp: Kiểm tra API Key trong appsettings.json.

404 Not Found

Token không tồn tại hoặc đã bị xóa.

Giải pháp: Tạo token mới.

Token hết lượt sử dụng

Token đã sử dụng hết maxUsage.

Giải pháp: Tạo token mới với maxUsage cao hơn.