Lịch sử thay đổi
Mọi lần sửa trang này, mới nhất ở trên. Mở từng mục để xem đã đổi gì.
- 02/10/2026 · +38 −46 dòng
Xem thay đổi
# 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 + > **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**. - Đặt key trong header `Authorization` của mọi request: + ## Gửi key {#send-the-key-as-a-bearer-token} ``` ⋯ ``` - 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. + 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ó. - 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. + | 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](reference/behaviour.md#authentication). + ## Scope {#scopes} - 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ệ. + Đâ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 | Ai tạo | + | Scope | Nhãn trên portal | Mở quyền | Cách lấy key có scope này | |---|---|---|---| - | `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é. + | `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:** 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). + > **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](concepts/security.md#leaked-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`. + 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 + ## Tạo key {#create-a-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. + 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** và tìm **Create a key**. + 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ì, 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 + 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. - Xoay vòng (rotate) thay secret của key nhưng giữ nguyên label và scope. + 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](../partners/developer-keys.md). - 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. + ## Xoay vòng và thu hồi {#rotate-a-key} - > **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ũ. + 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](concepts/security.md#key-lifecycle). - 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 {#revoke-a-key} - ## Thu hồi key + 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. - 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. + ## Giữ key trên server {#keep-keys-on-your-server} - 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. + - 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 + ## Liên quan {#related} + - [Bảo mật](concepts/security.md) - [Bắt đầu nhanh](quickstart.md) - - [Lỗi](concepts/errors.md): các response `401` và `403`. - - [Quản lý developer key trên portal](../partners/developer-keys.md) + - [Lỗi](concepts/errors.md)
- 01/10/2026 · +7 −5 dòng
Xem thay đổi
⋯ | `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 (granted by Wandura) | `POST /api/delivery/v1/playback` | Chỉ Wandura | + | `playback` | Play films | `POST /api/delivery/v1/playback` | Bạn, trên trang **Developers** | - Bạn không thể tự tạo key có scope `playback`. Một playback key bị lộ sẽ cho phép bất kỳ ai stream các phim bạn được cấp phép, nên Wandura cấp trực tiếp các key này. Khi sẵn sàng tích hợp playback, hãy xin key từ Wandura. + 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`. ⋯ 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 ít nhất một scope. + 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. ⋯ > **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` do Wandura xoay vòng: portal đánh dấu chúng là **Managed by Wandura** và không có nút **Rotate**. Hãy hỏi trong kênh Discord Wandura của team bạn. Để đổi không gián đoạn, Wandura tạo một playback key mới bên cạnh key cũ, bạn triển khai key mới, rồi Wandura thu hồi key cũ; trong lúc chuyển cả hai key đều chạy. + 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. - Developer có thể thu hồi các key được tạo trên portal. Chỉ **Admin** của tổ chức mới thu hồi được key có scope `playback`. Hãy dùng việc này như công tắc khẩn cấp nếu nghi playback key bị lộ, rồi xin Wandura key thay thế. + 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 ⋯
- 01/10/2026 · +1 −1 dòng
Xem thay đổi
⋯ > **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` do Wandura xoay vòng: portal đánh dấu chúng là **Managed by Wandura** và không có nút **Rotate**. Hãy nhờ Wandura xoay vòng giúp. + Key đã thu hồi không xoay vòng được; hãy tạo key mới. Key có scope `playback` do Wandura xoay vòng: portal đánh dấu chúng là **Managed by Wandura** và không có nút **Rotate**. Hãy hỏi trong kênh Discord Wandura của team bạn. Để đổi không gián đoạn, Wandura tạo một playback key mới bên cạnh key cũ, bạn triển khai key mới, rồi Wandura thu hồi key cũ; trong lúc chuyển cả hai key đều chạy. ## Thu hồi key ⋯
- 01/10/2026 · +2 −2 dòng
Xem thay đổi
⋯ | `playback` | Play films (granted by Wandura) | `POST /api/delivery/v1/playback` | Chỉ Wandura | - Bạn không thể tự tạo key có scope `playback`. Một playback key bị lộ sẽ cho phép bất kỳ ai stream các phim bạn được cấp phép, nên Wandura cấp trực tiếp các key này. Khi sẵn sàng tích hợp playback, hãy xin key từ đầu mối đối tác Wandura của bạn. + Bạn không thể tự tạo key có scope `playback`. Một playback key bị lộ sẽ cho phép bất kỳ ai stream các phim bạn được cấp phép, nên Wandura cấp trực tiếp các key này. Khi sẵn sàng tích hợp playback, hãy xin key từ Wandura. 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`. ⋯ > **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` do Wandura xoay vòng: portal đánh dấu chúng là **Managed by Wandura** và không có nút **Rotate**. Hãy nhờ đầu mối đối tác Wandura xoay vòng giúp. + Key đã thu hồi không xoay vòng được; hãy tạo key mới. Key có scope `playback` do Wandura xoay vòng: portal đánh dấu chúng là **Managed by Wandura** và không có nút **Rotate**. Hãy nhờ Wandura xoay vòng giúp. ## Thu hồi key ⋯
- 30/09/2026 · +1 −1 dòng
Xem thay đổi
⋯ 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`. 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. + 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 {#scopes} ⋯
- 29/09/2026 · Tạo trang