Partner Authentication

External API sử dụng API Key (X-API-Key) thay vì JWT để xác thực.

Authentication Header

Tất cả requests cần include header X-API-Key:

curl "https://api.cohost.vn/api/v1/external/listings" \
  -H "X-API-Key: ck_live_xxxxxxxxxxxx"

API Key Format

• Production: ck_live_xxxxxxxxxxxx
• Test: ck_test_xxxxxxxxxxxx

Scopes (Deprecated)

Lưu ý: Scope checking đã được bỏ. Chỉ cần API Key hợp lệ là đủ để truy cập tất cả endpoints.

Các scopes trước đây (không còn được sử dụng):

• listings:read, bookings:read, bookings:create
• customers:read, customers:write

Team Management

API Key có thể quản lý nhiều teams. Khi gọi API:

• Không cần header X-Team-ID: API tự động query từ tất cả teams mà token có quyền
• Filter theo teams: Sử dụng query parameter team_ids (JSON array) để filter theo các teams cụ thể

Ví dụ:

# Query từ tất cả teams trong token
curl "https://api.cohost.vn/api/v1/external/listings" \
  -H "X-API-Key: ck_live_xxxxxxxxxxxx"

# Filter theo teams cụ thể (chỉ các teams hợp lệ sẽ được sử dụng)
curl "https://api.cohost.vn/api/v1/external/listings?team_ids=[1,2,3]" \
  -H "X-API-Key: ck_live_xxxxxxxxxxxx"

Lưu ý:

• Format team_ids: JSON array string "[1,2,3]"
• Nếu team_ids chứa teams không thuộc token, các teams đó sẽ bị bỏ qua (chỉ filter các teams hợp lệ)
• Nếu không có team_ids, API sẽ trả về dữ liệu từ tất cả teams mà token quản lý

IP Whitelist (Optional)

Để tăng bảo mật, có thể config IP whitelist cho API Key. Chỉ request từ IP trong whitelist mới được accept.

Liên hệ team Cohost để config IP whitelist.

Two-layer Authentication khi dùng Customer Login

Khi sử dụng tính năng Customer Management, hệ thống có 2 lớp xác thực:

1. Giữa Partner ↔ Cohost External API: dùng API Key qua header X-API-Key.
2. Giữa Customer ↔ Auth0: dùng email/password để login, Auth0 trả về JWT token cho backend của bạn.

Luồng tạo tài khoản customer (register)

Dựa trên tài liệu domain Partner Customer Management, luồng chuẩn như sau:

1. Customer đăng ký trên website của partner (form: email, full_name, phone, password).
2. Backend của partner gọi POST /api/v1/external/customers/register với:
   • Header: X-API-Key: <partner_api_token> (yêu cầu scope customers:write).
   • Body: { "email", "full_name", "phone", "password" }.
3. Cohost:
   • Validate API Key (status, expiration, IP whitelist, team_ids).
   • Nếu email chưa tồn tại:
     • Tạo user trong Auth0 và gửi email verify.
     • Tạo user trong DB Cohost với created_source = PARTNER_API.
     • Thêm user vào tất cả team mà API token có quyền (bảng team_customers).
   • Nếu email đã tồn tại:
     • Chỉ thêm user vào các team mới mà token đang có, nếu có.
4. Response trả về user_id, danh sách teams và cờ requires_email_verification:
   • requires_email_verification = true: customer cần verify email trước khi có thể login.
   • requires_email_verification = false: user đã tồn tại và chỉ được thêm vào team mới.

Luồng đăng nhập customer (login)

Sau khi customer đã verify email, có 2 cách để customer đăng nhập:

Cách 1: Sử dụng External API Login Endpoint (Khuyến nghị)

Partner backend có thể gọi endpoint login trong External API để authenticate customer:

curl -X POST "https://api.cohost.vn/api/v1/external/customers/login" \
  -H "X-API-Key: ck_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "password": "SecurePassword123"
  }'

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "user_id": 200,
  "email": "customer@example.com",
  "full_name": "Nguyen Van A",
  "teams": [1, 2, 3]
}

Lưu ý:

• Endpoint này yêu cầu API Key của partner (X-API-Key)
• Auto-add membership: Nếu customer chưa có trong team_customers của các teams trong token, hệ thống sẽ tự động thêm vào với status ACTIVE
• Auto-reactivate: Nếu customer có membership nhưng status là INACTIVE, hệ thống sẽ tự động kích hoạt lại thành ACTIVE
• Không cần register trước: Customer chỉ cần có tài khoản Auth0 là có thể login, không cần phải đăng ký qua POST /customers/register trước
• Trả về JWT access_token để customer dùng với booking endpoints

Cách 2: Sử dụng Auth0 Universal Login hoặc SDK

1. Customer truy cập trang login của bạn (Auth0 Universal Login hoặc hosted page).
2. Customer login bằng email/password đã đăng ký.
3. Auth0 validate credentials và trả về JWT access token/id token cho frontend/backend của bạn.
4. Backend của bạn validate JWT (issuer, audience, signature) và lấy thông tin user:
   • sub / user_id trong Auth0.
   • Các claim khác (email, name, metadata nếu có).
5. Backend của bạn có thể dùng thông tin đó để:
   • Xác định customer tương ứng trong Cohost (mapping qua email hoặc auth0_id).
   • Lấy context team/customer thông qua các API nội bộ hoặc stored mapping.

Quan trọng:

• Customer không gọi trực tiếp Cohost External API; chỉ hệ thống partner gọi External API với X-API-Key.
• JWT của customer dùng để xác thực giữa frontend ↔ backend của partner; API Key dùng cho backend partner ↔ Cohost.
• Nếu customer chưa verify email, việc login sẽ bị chặn theo cấu hình Auth0 (email verification required).
• Sau khi login, customer sử dụng JWT token (access_token) để gọi booking endpoints với header Authorization: Bearer <token>.

Best Practices

1. Không hardcode API Key trong code:

   • Sử dụng environment variables
   • Không commit vào git

2. Rotating API Keys:

   • Thay đổi API Key định kỳ
   • Liên hệ team Cohost để revoke/regenerate

3. Rate Limiting:

   • Mỗi API Key có rate limit riêng
   • Xem headers X-RateLimit-* để theo dõi

JWT Bearer Authentication (Cho Customer Endpoints)

Sau khi customer đăng nhập thành công, họ nhận được JWT access_token để sử dụng với các booking endpoints trong internal API.

Sử dụng JWT Token

Customer sử dụng JWT token với header Authorization: Bearer <token>:

curl "https://api.cohost.vn/api/v1/bookings/my" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Customer Endpoints (Yêu cầu JWT Bearer)

Endpoint	Method	Description	Auth
/api/v1/checkout/preview	POST	Preview booking price	JWT Bearer
/api/v1/checkout/confirm	POST	Create booking	JWT Bearer
/api/v1/bookings/my	GET	Get customer bookings	JWT Bearer
/api/v1/bookings/{id}	GET	Get booking detail	JWT Bearer
/api/v1/auth/me	GET	Get customer profile	JWT Bearer
/api/v1/auth/me	PATCH	Update customer profile	JWT Bearer

Lưu ý quan trọng:

• Customer PHẢI verify email trước khi có thể tạo booking
• Nếu chưa verify, endpoint POST /api/v1/checkout/confirm sẽ trả về 403 Forbidden với error USER_NOT_VERIFIED
• JWT token có thời hạn (thường 24 giờ), cần handle token expiration

Error Codes

Code	HTTP Status	Description
API_TOKEN_NOT_FOUND	401	API Key không hợp lệ
API_TOKEN_EXPIRED	401	API Key đã hết hạn
API_TOKEN_INACTIVE	401	API Key bị vô hiệu hóa
EXTERNAL_INVALID_REQUEST	400	Invalid request format (e.g., invalid team_ids JSON format)
EXTERNAL_INVALID_STATE	400	Invalid state value
EXTERNAL_INVALID_DATE_FORMAT	400	Invalid date format
EXTERNAL_LISTING_NOT_ACCESSIBLE	404	Listing không tồn tại hoặc không thuộc teams của token
EXTERNAL_BOOKING_NOT_ACCESSIBLE	404	Booking không tồn tại hoặc không thuộc teams của token
EXTERNAL_CUSTOMER_NOT_ACCESSIBLE	403	Customer không thuộc teams của token
EXTERNAL_BOOKING_ID_REQUIRED	400	external_booking_id required when external_system provided
AUTH_INVALID_CREDENTIALS	401	Email hoặc password không đúng
USER_NOT_VERIFIED	403	User chưa verify email, không thể tạo booking
BOOKING_NOT_FOUND	404	Booking không tồn tại
OVERBOOKING	409	Listing không còn available cho ngày đã chọn

Related

• Quick Start
• Common Patterns
• Rate Limiting