Xác thực

Mọi yêu cầu đến các API của Felo API Platform đều yêu cầu xác thực bằng khóa API. Hướng dẫn này giải thích cách xác thực yêu cầu của bạn và xử lý các sự cố xác thực thường gặp.

Xác thực bằng khóa API

Felo sử dụng xác thực bằng khóa API cho mọi endpoint v2. Khóa API của bạn xác định ứng dụng và cung cấp quyền truy cập vào các khả năng của nền tảng.

Cách hoạt động

1. Bạn lấy khóa API từ trang API Keys của Felo API Platform
2. Bạn đưa khóa API vào header Authorization của mọi yêu cầu API
3. Nền tảng xác thực khóa API của bạn và xử lý yêu cầu

Định dạng header

Đưa khóa API của bạn vào header Authorization theo lược đồ xác thực Bearer:

Authorization: Bearer YOUR_API_KEY

Ví dụ yêu cầu

curl -X POST https://openapi.felo.ai/v2/chat \
  -H "Authorization: Bearer sk_live_abc123xyz789" \
  -H "Content-Type: application/json" \
  -d '{"query": "What is machine learning?"}'

Lấy khóa API của bạn

Để lấy khóa API:

1. Mở trang API Keys của Felo API Platform
2. Đăng nhập bằng tài khoản Felo nếu được yêu cầu
3. Nhập tên khóa và nhấp Create Key
4. Sao chép khóa đầy đủ khi nó xuất hiện. Khóa chỉ được hiển thị một lần
5. Lưu khóa an toàn và dùng nó làm FELO_API_KEY

Thực tiễn bảo mật tốt nhất

1. Lưu khóa API an toàn

Không nên gán cứng khóa API trong mã nguồn:

# ❌ Bad - API Key exposed in code
api_key = "sk_live_abc123xyz789"

Nên dùng biến môi trường hoặc cấu hình an toàn:

# ✅ Good - API Key from environment
import os
api_key = os.environ.get('FELO_API_KEY')

2. Dùng biến môi trường

Lưu khóa API trong biến môi trường:

Linux/macOS:

export FELO_API_KEY="sk_live_abc123xyz789"

Windows (Command Prompt):

set FELO_API_KEY=sk_live_abc123xyz789

Windows (PowerShell):

$env:FELO_API_KEY="sk_live_abc123xyz789"

3. Xoay vòng khóa định kỳ

Định kỳ tạo khóa API mới và thu hồi khóa cũ để giảm thiểu rủi ro bảo mật.

4. Dùng khóa khác nhau cho môi trường khác nhau

Tạo các khóa API riêng cho môi trường phát triển, staging và production.

5. Không bao giờ để lộ khóa trong mã phía máy khách

Khóa API chỉ nên được dùng trong mã phía máy chủ. Không bao giờ đưa chúng vào:

• Mã JavaScript frontend
• Mã nguồn ứng dụng di động
• Kho lưu trữ công khai
• Tệp cấu hình phía máy khách

Lỗi xác thực

Để xem đầy đủ cấu trúc lỗi, header giới hạn tần suất và chính sách thử lại, hãy xem Lỗi, giới hạn và thử lại.

Mã lỗi thường gặp

Yêu cầu bị từ chối trả về trạng thái khóa trong message:

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "API Key is required",
  "request_id": "..."
}

status là mã trạng thái HTTP. Khóa đã bị thu hồi báo API Key has been revoked (keyPrefix=...). Hãy phân nhánh theo trạng thái HTTP và code, không dựa vào nội dung chính xác của message.

Khắc phục sự cố

Nếu xác thực thất bại:

1. Kiểm tra rằng header chính xác là Authorization: Bearer YOUR_API_KEY.
2. Xác nhận khóa chưa bị thu hồi trên trang API Keys.
3. Xác nhận môi trường đang dùng đúng khóa bạn mong đợi.
4. Tạo khóa mới nếu khóa cũ đã bị xóa hoặc xoay vòng. Khóa đầy đủ chỉ được hiển thị một lần, tại thời điểm tạo.

Để xem danh sách kiểm tra bắt đầu từ triệu chứng, bao gồm xác thực và phần còn lại của nền tảng, hãy xem Khắc phục sự cố.

Ví dụ: Gỡ lỗi xác thực

import requests

url = "https://openapi.felo.ai/v2/chat"
api_key = "YOUR_API_KEY"

# Correct format
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers, json={"query": "test"})

if response.status_code == 401:
    error = response.json()
    print(f"Authentication failed: {error['code']}")
    print(f"Message: {error['message']}")
    print(f"Request ID: {error['request_id']}")
else:
    print("Authentication successful!")

Giới hạn tần suất

Giới hạn tần suất được áp dụng theo từng endpoint, không áp dụng toàn cục theo khóa API. Hiện tại chỉ `/v2/chat` áp dụng các giới hạn này; người dùng có gói đăng ký Felo trả phí đang hiệu lực được miễn. Các endpoint /v2/** khác không có giới hạn tần suất được áp dụng.

Phản hồi 429 bao gồm các header X-RateLimit-* và Retry-After. Luôn đọc giới hạn hiệu lực từ header phản hồi, không dựa vào tài liệu.

Để xem đầy đủ các chiều giới hạn tần suất, header và chính sách thử lại, hãy xem Lỗi, giới hạn và thử lại.

Cần trợ giúp?

Nếu bạn gặp sự cố xác thực:

1. Xem lại hướng dẫn này một cách cẩn thận
2. Xem hướng dẫn Bắt đầu
3. Xác minh khóa API của bạn trên trang API Keys
4. Liên hệ hỗ trợ tại [email protected] kèm request ID của bạn

Các bước tiếp theo

• Hướng dẫn bắt đầu - Tìm hiểu cách thực hiện lệnh gọi API đầu tiên
• Tham chiếu Chat API - Khám phá tài liệu Chat API