PlayableLabs Docs

Quy trình JWT session, xác thực API token, phạm vi token và ví dụ code cho PlayableLabs API

Phương Thức Xác Thực

PlayableLabs hỗ trợ hai phương thức xác thực:

JWT session -- Cho truy cập qua trình duyệt web app
API token -- Cho server-to-server và quy trình tự động hóa

Cả hai phương thức đều sử dụng header Authorization: Bearer <token>.

Xác Thực JWT Session

Ứng dụng web sử dụng NextAuth v5 để quản lý session. Quy trình này được xử lý tự động khi bạn đăng nhập qua trình duyệt.

Cách Hoạt Động

Người dùng đăng nhập qua email/mật khẩu hoặc Google OAuth
NextAuth cấp JWT session token (thời hạn 7 ngày)
Token được lưu trong HTTP-only cookie
Tất cả request tiếp theo tự động bao gồm token
Token được tự động làm mới trước khi hết hạn

JWT session chỉ dành cho trình duyệt. Để truy cập lập trình, sử dụng API token.

Xác Thực API Token

API token là phương thức khuyến nghị cho script, CI/CD pipeline và tích hợp bên ngoài.

Tạo Token

Tạo token từ Developers > Tokens. Mỗi token thuộc một tổ chức và có phạm vi quyền cụ thể.

Sử Dụng Token

Thêm token vào header Authorization:

curl -X GET \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  https://api.playablelabs.ai/api/games

Ví Dụ TypeScript

const API_BASE = 'https://api.playablelabs.ai/api'

async function listGames(token: string): Promise<unknown> {
  const response = await fetch(`${API_BASE}/games`, {
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
  })

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`)
  }

  return response.json()
}

const games = await listGames('YOUR_TOKEN')

Ví Dụ cURL

Danh sách game:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.playablelabs.ai/api/games

Tạo game:

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Game", "organizationId": "YOUR_ORG_ID"}' \
  https://api.playablelabs.ai/api/games

Kích hoạt xuất:

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"variantId": "VARIANT_ID", "network": "unity"}' \
  https://api.playablelabs.ai/api/export

Phạm Vi Token

Mỗi API token có tập hợp phạm vi quyền kiểm soát quyền truy cập. Xem trang API Tokens để biết đầy đủ.

Request vượt quá phạm vi token sẽ trả về:

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions. Required: games:write"
}

Response Lỗi

Status	Ý nghĩa	Nguyên nhân thường gặp
401	Unauthorized	Token thiếu, hết hạn hoặc không hợp lệ
403	Forbidden	Token thiếu phạm vi quyền cần thiết

Xử Lý Lỗi 401

async function safeRequest(url: string, token: string) {
  const res = await fetch(url, {
    headers: { 'Authorization': `Bearer ${token}` },
  })

  if (res.status === 401) {
    console.error('Xác thực thất bại. Kiểm tra lại token.')
    return null
  }

  return res.json()
}

Khuyến Nghị Bảo Mật

Lưu token trong biến môi trường, không trong mã nguồn
Sử dụng HTTPS cho tất cả request API (mặc định bắt buộc)
Xoay vòng token mỗi 90 ngày
Thu hồi token không sử dụng ngay
Cấp quyền tối thiểu cần thiết cho mỗi tích hợp

Bước Tiếp Theo

Tổng Quan API -- Endpoint, phân trang và rate limit
SDK và Ví Dụ -- Code client sẵn dùng

Xác Thực

On this page