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

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. 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
• Lỗi: các response 401 và 403.
• Quản lý developer key trên portal