Xác thực

Mọi endpoint (trừ /health) đều bắt buộc gửi kèm API key của tenant qua header X-Api-Key:

X-Api-Key: omx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Lấy và quản lý API key

  • Tạo và quản lý key trong ứng dụng web OMICX → Integrations → API Keys.
  • Key luôn bắt đầu bằng tiền tố omx_, theo sau là một chuỗi ngẫu nhiên.
  • Key chỉ hiển thị đầy đủ đúng một lần khi tạo — hãy lưu ngay vào nơi an toàn (server-side, secret manager). OMICX chỉ lưu bản băm (hash) của key nên không thể khôi phục nếu bạn làm mất.
  • Không nhúng key vào code chạy phía trình duyệt, ứng dụng mobile, hay đẩy lên repo công khai. Nếu lỡ lộ, hãy thu hồi và tạo key mới ngay trong web app.

Scope (phạm vi quyền)

Mỗi key mang theo một tập scope quy định nó được gọi những endpoint nào:

accessTypeÝ nghĩa
FULLKey được gọi tất cả endpoint.
SCOPEDKey chỉ được gọi những endpoint có scope nằm trong whitelist.

Scope yêu cầu cho từng endpoint:

EndpointScope yêu cầu
POST /ttstts:execute
POST /sttstt:execute
POST /webhooks, PUT /webhooks/{webhookId}, DELETE /webhooks/{webhookId}webhooks:manage

Một key hợp lệ nhưng thiếu scope sẽ nhận về 403 INSUFFICIENT_SCOPE (không phải 401). Cách khắc phục: chỉnh sửa scope của key trong web app — key gốc vẫn giữ nguyên, không cần tạo lại.

Lỗi xác thực

1{
2  "error": {
3    "code": "UNAUTHORIZED",
4    "subCode": "API_KEY_INVALID",
5    "message": "API key thiếu hoặc không hợp lệ.",
6    "timestamp": "2026-01-01T00:00:00Z",
7    "path": "/public-svc/api/ai/tts"
8  }
9}