Bảo Mật

Quản Lý Khóa API

• Không bao giờ hardcode khóa — Dùng biến môi trường hoặc trình quản lý secrets (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault)
• Không bao giờ commit khóa vào git — Thêm .env vào .gitignore. Dùng git-secrets hoặc truffleHog để quét lịch sử repo
• Dùng khóa riêng cho từng môi trường — Khóa dev / staging / production độc lập với nhau. Nếu khóa dev bị lộ, production không bị ảnh hưởng
• Phân quyền cho mọi khóa — Giới hạn truy cập mô hình, đặt giới hạn chi tiêu và whitelist IP cho mỗi khóa tại thời điểm tạo

Xoay Vòng Khóa

Xoay vòng khóa API mỗi 90 ngày. Dưới đây là quy trình xoay vòng an toàn có xác thực:

import os
import requests

# Step 1: Create new key via Dashboard or API
NEW_KEY = "sk-new-key-from-dashboard"

# Step 2: Update environment (do this atomically with your deploy)
# In production, use a secrets manager: AWS Secrets Manager, GCP Secret Manager, or Vault
os.environ["TOKSPAN_API_KEY"] = NEW_KEY

# Step 3: Verify new key works
response = requests.post(
    "https://api.tokspan.com/v1/chat/completions",
    headers={"Authorization": f"Bearer {NEW_KEY}"},
    json={"model": "gpt-4o", "messages": [{"role": "user", "content": "ping"}]},
    timeout=10,
)
assert response.status_code == 200, f"New key validation failed: {response.status_code}"

# Step 4: Revoke old key in Dashboard → API Keys
# Only do this AFTER confirming new key works in production
print("New key validated. Revoke old key in Dashboard now.")

Backend Proxy (Bắt Buộc cho Trình Duyệt/Di Động)

Không bao giờ gọi TokSpan trực tiếp từ mã phía client. Khóa API bị lộ trong trình duyệt hoặc ứng dụng di động có thể bị trích xuất bởi bất kỳ ai. Luôn định tuyến qua backend của bạn:

Browser App → Your Backend API → TokSpan API
                      ↑
              API key lives here
          (never reaches the client)

Backend của bạn xác thực phiên người dùng, sau đó chuyển tiếp request AI với khóa API phía máy chủ. Client không bao giờ nhìn thấy khóa.

Danh Sách Trắng IP

Giới hạn mỗi khóa API cho các địa chỉ IP hoặc dải CIDR cụ thể. Ngay cả khi khóa bị lộ, nó cũng vô dụng từ các mạng không được phép. Cấu hình tại Dashboard → API Keys → Edit → IP Whitelist. Với khóa production, chỉ whitelist IP outbound của máy chủ backend.

Bật MFA

Bảo vệ tài khoản TokSpan Dashboard của bạn bằng xác thực đa yếu tố. Có sẵn qua ứng dụng xác thực TOTP (Google Authenticator, Authy, 1Password). Bật tại Dashboard → Settings → Security → MFA.

Kiểm Tra & Giám Sát

Ghi nhật ký mức sử dụng khóa để phát hiện bất thường:

# Monitor API key usage via response headers
import logging

def audit_request(response, key_name):
    usage = response.json().get("usage", {})
    logging.info(f"[{key_name}] model={response.json()['model']} "
                 f"tokens={usage.get('total_tokens', 0)} "
                 f"remaining_rpm={response.headers.get('x-ratelimit-remaining-requests', '?')}")

Trong Bảng điều khiển, thường xuyên xem lại Activity Logs cho từng khóa. Tìm kiếm: mức sử dụng mô hình bất thường, token tăng đột biến, request từ IP lạ hoặc khung giờ bất thường.

Nếu Khóa Bị Xâm Phạm

1. Thu hồi ngay lập tức — Dashboard → API Keys → Revoke (có hiệu lực trong <60 giây)
2. Tạo khóa mới — và cập nhật ứng dụng của bạn
3. Kiểm tra nhật ký của khóa cũ — Kiểm tra mọi mức sử dụng trái phép trước khi xóa
4. Điều tra cách nó bị lộ — Kiểm tra lịch sử git, nhật ký CI, thông báo lỗi, mã phía client
5. Thắt chặt phạm vi — Thêm IP whitelisting và giảm giới hạn chi tiêu cho khóa thay thế