# Xác thực

Mọi request tới Delivery API đều được xác thực bằng một API key thuộc về tổ chức của bạn. Trang này giải thích cách gửi key, mỗi scope mở quyền gì, cách lấy key, và cách xoay vòng hoặc thu hồi key.

## Gửi key dưới dạng bearer token

Đặt key trong header `Authorization` của mọi request:

```
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.

Thiếu header, header sai định dạng, hoặc key đã bị thu hồi hay không tồn tại đều trả về `401`. Nếu Wandura chưa kiểm được key kịp lúc, bạn nhận `503` với `error_code` `service_unavailable` (creatives: `code` `5031`) kèm header `Retry-After`: key vẫn đúng, hãy thử lại chứ đừng xoay key. API không dùng cookie và không có danh tính theo từng người dùng: một key đại diện cho cả tổ chức.

## Scope
Mỗi key mang một hoặc nhiều scope. Endpoint từ chối key thiếu scope của nó bằng `403`, kể cả khi key đó hợp lệ.

| Scope | Nhãn trên portal | Mở quyền | Ai tạo |
|---|---|---|---|
| `metadata:read` | Read film metadata | `GET /api/delivery/v1/catalog` | Bạn, trên trang **Developers** |
| `creatives:export` | Receive exported creatives | `GET /api/delivery/v1/creatives` và `GET /api/delivery/v1/creatives/{id}` | Bạn, trên trang **Developers** |
| `webhooks:manage` | Manage webhooks | Chưa có endpoint nào dùng scope này | Bạn, trên trang **Developers** |
| `playback` | Play films | `POST /api/delivery/v1/playback` | Bạn, trên trang **Developers** |

Bạn tự tạo key có scope `playback` như mọi key khác: trên **Developers**, chọn **Stream films in an app**. Key nhận `metadata:read` và `playback`, nên cùng một server vừa liệt kê được phim vừa xin được vé.

> **Cảnh báo:** Nếu playback key bị lộ, bất kỳ ai cũng stream được các phim bạn được cấp phép. Chỉ giữ key trên server, và thu hồi ngay nếu nghi key đã bị lộ. Mỗi lần có playback key mới, hoặc một playback key được xoay vòng, Wandura nhận một cảnh báo ghi tổ chức của bạn, người tạo và tiền tố của key (không bao giờ ghi bản thân key).

Chỉ cấp cho mỗi key những scope nó cần. Một job đồng bộ marketing cần `creatives:export`, không 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). Các vai trò khác không quản lý được key.

1. Mở **Developers** và tìm **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ì, ví dụ **Stream films in an app** cho playback key, hoặc tự chọn scope trong **Advanced: choose scopes**.
4. Chọn **Create key**, rồi sao chép key trước khi đóng thông báo.

Key đầy đủ chỉ hiện một lần. Wandura chỉ lưu dấu vân tay (fingerprint) của key và không thể hiện lại key cho bạn. Nếu làm mất key, hãy xoay vòng key đó hoặc tạo key mới.

Danh sách key hiển thị prefix, label, scope và lần dùng gần nhất của từng key, để bạn phát hiện key không còn dùng nữa.

## Giữ key trên server

- Chỉ gọi API từ backend. Các endpoint không gửi header CORS nên lệnh gọi từ trình duyệt sẽ thất bại, và key nằm trong trang web hoặc app di động có thể bị trích xuất.
- Lưu key trong secrets manager hoặc biến môi trường, không bao giờ đưa vào source control.
- Dùng key riêng cho từng hệ thống và từng môi trường, để 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 hiển thị trên portal.

## Xoay vòng key

Xoay vòng (rotate) thay secret của key nhưng giữ nguyên label và scope.

1. Trên **Developers**, chọn **Rotate** cạnh key và xác nhận.
2. Sao chép key mới. Key chỉ hiện một lần.
3. Triển khai key mới lên backend.

> **Cảnh báo:** Key cũ ngừng hoạt động ngay khi bạn xác nhận. Để xoay vòng mà không gián đoạn, hãy tạo key thứ hai với cùng scope, triển khai nó, rồi mới thu hồi key cũ.

Key đã thu hồi không xoay vòng được; hãy tạo key mới. Key có scope `playback` xoay vòng y như vậy, do bất kỳ **Admin** hoặc **Developer** nào của tổ chức bạn. Với playback key, đổi không gián đoạn càng quan trọng: tạo playback key thứ hai, triển khai nó, rồi mới thu hồi key cũ.

## Thu hồi key

Chọn **Revoke** cạnh key và xác nhận. Mọi thứ đang dùng key ngừng hoạt động ngay lập tức, và key đã thu hồi không khôi phục được.

Bất kỳ **Admin** hoặc **Developer** nào của tổ chức cũng thu hồi được mọi key của tổ chức, kể cả key có scope `playback` và key Wandura tạo giúp bạn. Nếu nghi playback key bị lộ, hãy thu hồi ngay: đó là công tắc khẩn cấp của bạn. Sau đó tạo playback key mới cho server.

## Liên quan

- [Bắt đầu nhanh](https://docs.wandura.ai/vi/developers/quickstart)
- [Lỗi](https://docs.wandura.ai/vi/developers/concepts/errors): các response `401` và `403`.
- [Quản lý developer key trên portal](https://docs.wandura.ai/vi/partners/developer-keys)