# Xác thực

> **TL;DR** — Gửi `Authorization: Bearer <API key>` ở mọi request, và chỉ từ server của bạn. Mỗi key thuộc về tổ chức của bạn và mang các scope; bảng bên dưới là nơi duy nhất cho biết scope nào mở endpoint nào. Admin và Developer tự tạo, xoay vòng và thu hồi key trên partner.wandura.ai → **Developers**.

## Gửi key
```
Authorization: Bearer wnd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Chữ `Bearer`, một dấu cách, rồi đến key. Key bắt đầu bằng `wnd_live_`, giúp công cụ quét secret phát hiện key lỡ bị commit. Các ví dụ đọc key từ biến môi trường `WANDURA_API_KEY`; mỗi hệ thống bạn chạy đặt biến này bằng key riêng của nó.

| Bạn nhận | Khi nào |
|---|---|
| `401`, không có `error_code` | Thiếu header hoặc header sai định dạng, hoặc key không tồn tại hay đã bị thu hồi. |
| `403`, không có `error_code` | Key hợp lệ nhưng thiếu scope của endpoint. |
| `503` `service_unavailable` | Wandura chưa kiểm được key kịp lúc. Key vẫn đúng: thử lại sau `Retry-After`, đừng bao giờ xoay key vì lỗi này. |
| `400` `unsupported_version` | Được kiểm trước key: header `Wandura-Version` của bạn không phải phiên bản được hỗ trợ. |

Một key đại diện cho cả tổ chức: API không có định danh theo từng người xem và không dùng cookie. Mọi quy tắc gom ở một chỗ: [Hành vi chuẩn của API](https://docs.wandura.ai/vi/developers/reference/behaviour#authentication).

## Scope
Đây là bảng scope duy nhất trong bộ tài liệu này; các trang khác đều link về đây.

| Scope | Nhãn trên portal | Mở quyền | Cách lấy key có scope này |
|---|---|---|---|
| `metadata:read` | Read film metadata | `GET /catalog` | **Developers** → **Sync catalog to your CMS** (hoặc **Stream films in an app**) |
| `playback` | Play films | `POST /playback` | **Developers** → **Stream films in an app** (đi kèm `metadata:read`) |
| `creatives:export` | Receive exported creatives | `GET /creatives`, `GET /creatives/{id}` | **Developers** → **Receive creatives / webhooks** |
| `videos:read` | Read open video (needs an app) | `GET /videos`, `GET /videos/{id}` | **Developers** → **Stream open video (fitness…)**; key được gắn với một app bạn đăng ký |
| scope bất kỳ | — | `GET /config` | Key hợp lệ bất kỳ |
| `webhooks:manage` | Manage webhooks | Không có gì: **để dành**. Hiện chưa có webhook; hãy gọi định kỳ các feed. | Tự động thêm khi chọn **Receive creatives / webhooks**; không mở quyền gì |

> **Cảnh báo:** Key có `playback` stream được các phim bạn được cấp phép. Nếu key bị lộ, bất kỳ ai cũng stream được. Hãy giữ key trên server và thu hồi ngay khi nghi key bị lộ: xem [Bảo mật](https://docs.wandura.ai/vi/developers/concepts/security#leaked-key).

Chỉ cấp cho mỗi key những scope mà hệ thống của nó cần: job đồng bộ catalog cần `metadata:read`, job marketing cần `creatives:export`, không bao giờ cần `playback`.

## Tạo key
Thành viên có vai trò **Admin** hoặc **Developer** quản lý key trên trang **Developers** của [partner.wandura.ai](https://partner.wandura.ai).

1. Mở **Developers** → **Create a key**.
2. Nhập **Label** (tối đa 80 ký tự) cho biết key chạy ở đâu, ví dụ `catalog-sync-prod`.
3. Chọn key dùng để làm gì (các mục đích ở trên), hoặc tự chọn scope trong **Advanced: choose scopes**.
4. Chọn **Create key** và sao chép key ngay. Key chỉ hiện **một lần**: Wandura chỉ lưu dấu vân tay (fingerprint) của key.

Danh sách key hiển thị prefix, label, scope và **Last used** của từng key. Các màn hình từng bước: [Developer key](https://docs.wandura.ai/vi/partners/developer-keys).

## Xoay vòng và thu hồi
Xoay vòng (rotate) thay secret của key nhưng giữ nguyên label, scope và phiên bản API đã ghim; thu hồi (revoke) thì chấm dứt key vĩnh viễn. Cả hai có hiệu lực trong vài giây, không có thời gian ân hạn, và không bao giờ chặn các vé đã cấp. Thời gian cụ thể, cách đổi key không gián đoạn và quy trình xử lý key bị lộ nằm ở [Bảo mật](https://docs.wandura.ai/vi/developers/concepts/security#key-lifecycle).

### Thu hồi
Bất kỳ Admin hoặc Developer nào cũng thu hồi được mọi key của tổ chức, kể cả playback key. Key đã thu hồi không khôi phục hay xoay vòng được: hãy tạo key mới.

## Giữ key trên server
- Chỉ gọi API từ backend. Lệnh gọi từ trình duyệt sẽ thất bại (không có CORS), và key nằm trong app có thể bị trích xuất.
- Mỗi hệ thống và mỗi môi trường một key, để thu hồi một key mà không ảnh hưởng các key khác.
- Không bao giờ ghi log key đầy đủ. Khi liên hệ hỗ trợ, hãy trích prefix của key.

## Liên quan
- [Bảo mật](https://docs.wandura.ai/vi/developers/concepts/security)
- [Bắt đầu nhanh](https://docs.wandura.ai/vi/developers/quickstart)
- [Lỗi](https://docs.wandura.ai/vi/developers/concepts/errors)