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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxChữ 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.
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ó
playbackstream đượ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.
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.
- Mở Developers → Create a key.
- Nhập Label (tối đa 80 ký tự) cho biết key chạy ở đâu, ví dụ
catalog-sync-prod. - 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.
- 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.
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.
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
Cập nhật 05/10/2026 · Lịch sử thay đổi (6)