> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.omicx.one/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.omicx.one/_mcp/server.

# API Keys

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                                                       |
| ---------- | ------------------------------------------------------------- |
| `FULL`     | Key được gọi tất cả endpoint.                                 |
| `SCOPED`   | Key chỉ được gọi những endpoint có scope nằm trong whitelist. |

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

| Endpoint                                                                                                                                              | Scope yêu cầu                           |
| ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `POST /tts`                                                                                                                                           | `tts:execute`                           |
| `POST /stt`                                                                                                                                           | `stt:execute`                           |
| Tạo, cập nhật, xoá, bật/tắt [Webhook](/integrations/webhooks/list-webhooks)                                                                           | `webhook:write`                         |
| Danh sách, danh mục sự kiện, tra cứu lịch sử gửi [Webhook](/integrations/webhooks/list-webhooks)                                                      | `webhook:read`                          |
| Tạo, cập nhật, xoá [Khách hàng](/customers/info/create-customer) và các thao tác tương tác                                                            | `customer:write`                        |
| Chi tiết, tìm kiếm [Khách hàng](/customers/info/create-customer) và toàn bộ endpoint [Cấu hình](/customer-config/attributes/list-customer-attributes) | `customer:read`                         |
| [Tạo link đánh giá](/feedbacks/manage/issue-feedback-token)                                                                                           | `customer:write`                        |
| [Chi tiết đánh giá](/feedbacks/manage/get-feedback), [Tìm bản mẫu đánh giá](/feedbacks/manage/search-feedback-templates)                              | `customer:read`                         |
| [Gửi câu trả lời đánh giá](/feedbacks/manage/submit-feedback)                                                                                         | Không cần API key — xác thực bằng token |

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

```json
{
  "error": {
    "code": "UNAUTHORIZED",
    "subCode": "API_KEY_INVALID",
    "message": "API key thiếu hoặc không hợp lệ.",
    "timestamp": "2026-01-01T00:00:00Z",
    "path": "/tts"
  }
}
```