Quickstart — REST API server-to-server

Core API mô tả bằng OpenAPI 3.1 (zod-openapi). Quickstart này đi qua luồng tối thiểu để mở một phiên cho người dùng đã xác thực trong hệ thống của bạn.

1. Tạo API key

Trong Studio, mở mục API key và tạo key mới. Key có dạng avk_…, hệ thống chỉ lưu hash. Scope mặc định cho phép tạo phiên (session.create). Key chỉ dùng từ server của bạn — không đặt vào code trình duyệt.

2. Cấp session token

curl -X POST https://api.avatin.ai/v1/sessions/token \
  -H "Authorization: Bearer avk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "<uuid của agent>",
    "channel": "sdk",
    "variables": { "customer_name": "Minh", "card_tier": "Platinum" }
  }'

Phản hồi:

{ "token": "eyJhbGciOiJFUzI1NiIs…", "expiresAt": "…", "expiresIn": 600 }

• Token là JWT ES256, dùng một lần, TTL 10 phút. Biến variables KHÔNG nằm trong JWT — lưu ở server và validate theo schema biến của agent lúc đổi token.
• Chỉ biến đã khai báo trong tab Biến của agent mới tới được agent.

3. Đổi token lấy phiên

Client (trình duyệt/app) đổi token lấy thông tin kết nối — không cần khoá:

curl -X POST https://api.avatin.ai/v1/public/sessions/exchange \
  -H "Content-Type: application/json" \
  -H "Origin: https://app.cua-ban.vn" \
  -d '{ "token": "eyJhbGciOiJFUzI1NiIs…" }'

Phản hồi:

{
  "sessionId": "…",
  "livekitUrl": "wss://…",
  "accessToken": "…",
  "endToken": "…",
  "expiresAt": "…"
}

• accessToken nối phòng LiveKit qua WebRTC (SDK Web lo phần này).
• endToken gọi POST /v1/public/sessions/{id}/end khi người dùng kết thúc — nhả slot và phút ngay, không đợi timeout.
• Core API kiểm tra Origin theo allowlist của agent trước khi tiêu token.

4. Kết thúc phiên

curl -X POST https://api.avatin.ai/v1/public/sessions/{sessionId}/end \
  -H "Content-Type: application/json" \
  -d '{ "endToken": "…" }'

Mã lỗi chuẩn

Mọi lỗi trả { code, message, details }:

Mã	HTTP	Nghĩa
INVALID_SESSION_TOKEN	401	Token sai/hết hạn/đã dùng
ORIGIN_NOT_ALLOWED	403	Origin không nằm trong allowlist của agent
ENTITLEMENT_REQUIRED	402	Vượt hạn mức của tổ chức (token chưa bị tiêu)
RATE_LIMITED	429	Quá nhiều yêu cầu

Lưu ý bảo mật

• Không nhận tham số từ trình duyệt để đổi agent/tổ chức/biến — backend tự quyết định từ phiên đăng nhập của nó.
• Nên kiểm tra Origin cùng-site ở route cấp token của bạn (chặn cross-site gọi trộm).
• Mọi thao tác tạo phiên được ghi audit log ở phía Avatin.