X-Team-ID Header Guide

Vấn đề

Một user có thể thuộc nhiều Team với các role khác nhau. Khi gọi API, backend cần biết đang làm việc với Team nào để:

• Validate quyền truy cập đúng role
• Lọc dữ liệu đúng Team
• Áp dụng cấu hình đúng Team

Giải pháp

Gửi X-Team-ID header trong mỗi request để chỉ định Team context. Header name không phân biệt hoa thường, nhưng trong tài liệu và code nên chuẩn hóa là X-Team-ID.

GET /api/v1/listings
Authorization: Bearer <jwt_token>
X-Team-ID: <team_id>

Endpoints yêu cầu X-Team-ID

Hầu hết các endpoint liên quan đến dữ liệu của Team đều yêu cầu header này:

Nhóm	Ví dụ endpoint
Listings	GET /api/v1/listings
Bookings	GET /api/v1/bookings
Financial	GET /api/v1/financial/transactions
Members	GET /api/v1/teams/{team_id}/members
Notifications	GET /api/v1/notifications

Endpoints KHÔNG yêu cầu X-Team-ID

Endpoint	Lý do
GET /api/v1/teams	Lấy danh sách tất cả team của user
POST /api/v1/teams	Tạo team mới
GET /api/v1/catalogs	Dữ liệu public
GET /api/v1/locations/*	Dữ liệu public
GET /api/v1/search	Tìm kiếm public

Lỗi thường gặp

HTTP	Mô tả	Cách xử lý
400 Bad Request	Thiếu header X-Team-ID	Thêm header vào request
403 Forbidden	User không thuộc Team này	Kiểm tra lại team_id
404 Not Found	Team không tồn tại	Kiểm tra lại team_id

Ví dụ — Axios Interceptor (Frontend)

// Tự động thêm X-Team-ID vào mọi request
axios.interceptors.request.use((config) => {
  const teamId = getCurrentTeamId(); // lấy từ store/context
  if (teamId) {
    config.headers['X-Team-ID'] = teamId;
  }
  return config;
});

Ví dụ — cURL

curl https://api.cohost.vn/api/v1/bookings \
  -H "Authorization: Bearer <token>" \
  -H "X-Team-ID: <team_id>"

Ví dụ — Python

import httpx

headers = {
    "Authorization": f"Bearer {token}",
    "X-Team-ID": str(team_id),
}

response = httpx.get(
    "https://api.cohost.vn/api/v1/bookings",
    headers=headers,
)

Flow

User đăng nhập
      ↓
Lấy danh sách teams: GET /api/v1/teams
      ↓
User chọn Team (hoặc auto-select nếu chỉ có 1)
      ↓
Lưu team_id vào state/context
      ↓
Mọi request tiếp theo đều kèm X-Team-ID: <team_id>