Mọi yêu cầu API của Telm được xác thực bằng một khoá API bắt đầu bằng tk_live_ — không bao giờ bằng thông tin đăng nhập bảng điều khiển của bạn. Tạo một khoá trong tài khoản của bạn, gửi nó trong header Authorization dưới dạng một token Bearer, và nó hành động thay mặt tài khoản của bạn trên các nhóm nơi bạn là quản trị viên. Nếu một khoá bị rò rỉ, hãy thu hồi nó trong bảng điều khiển và cấp một khoá mới.
1Cách các khoá API hoạt động
REST API của Telm không dùng phiên trình duyệt của bạn. Thay vào đó, mỗi yêu cầu mang theo một khoá API — một chuỗi bí mật dài bắt đầu bằng tiền tố tk_live_ theo sau là các ký tự ngẫu nhiên. Khoá này xác định tài khoản của bạn và cấp quyền cho lệnh gọi.
Bạn tạo các khoá từ tài khoản của mình và có thể giữ nhiều khoá cùng lúc (ví dụ, một khoá cho mỗi script hoặc dịch vụ). Bí mật đầy đủ chỉ được hiển thị một lần, tại thời điểm tạo; sau đó bảng điều khiển liệt kê một khoá theo tiền tố ngắn của nó (tk_live_ cộng với vài ký tự đầu tiên) để bạn nhận ra nó, và giá trị đầy đủ không bao giờ được giữ lại sau đó.
- Một khoá trông giống tk_live_ theo sau là một chuỗi ngẫu nhiên dài.
- Các khoá được tạo và quản lý trong bảng điều khiển của bạn.
- Bí mật đầy đủ chỉ hiển thị một lần — hãy sao chép nó ngay lập tức và lưu ở nơi an toàn.
- Hãy đối xử với một khoá như một mật khẩu: bất kỳ ai có nó đều có thể gọi API với danh nghĩa bạn.
2Gửi khoá cùng mỗi yêu cầu
Truyền khoá trong header Authorization dùng lược đồ Bearer. Giá trị của header là từ Bearer, một dấu cách, rồi đến khoá của bạn — ví dụ, Authorization: Bearer tk_live_your_key_here.
Với các client không thể đặt header Authorization một cách tiện lợi, API cũng chấp nhận khoá trong một header X-API-Key. Nếu cả hai đều có, header Authorization thắng. Các yêu cầu qua bất cứ thứ gì khác ngoài HTTPS đều không được chấp nhận trong môi trường production.
- Ưu tiên: gửi Authorization: Bearer tk_live_...
- Thay thế: gửi khoá trong header X-API-Key.
- URL cơ sở cho mọi lệnh gọi là api.telm.com/api/public/v1.
- Xem danh sách endpoint đầy đủ và các schema trên trang dành cho nhà phát triển.
3Một khoá có thể truy cập những gì
Một khoá hành động nghiêm ngặt thay mặt tài khoản của bạn. Nó chỉ có thể đọc hoặc thay đổi các nhóm nơi tài khoản của bạn là quản trị viên — một yêu cầu nhắm tới bất kỳ nhóm nào khác trả về 404, nên API không bao giờ tiết lộ rằng một nhóm bạn không thể quản lý thậm chí có tồn tại.
Quyền truy cập cũng phụ thuộc vào gói của nhóm mục tiêu. Endpoint kiểm tra spam mở cho mọi gói trong hạn mức hằng ngày, trong khi API đầy đủ (quy tắc, cài đặt, danh sách trắng, nhật ký, phân tích, kiểm tra hàng loạt và webhook) khả dụng trên gói Pro trở lên đối với nhóm liên quan.
- Một khoá chỉ có thể chạm tới các nhóm nơi bạn là quản trị viên.
- Các yêu cầu tới những nhóm bạn không quản lý trả về 404, không phải 403.
- Hạn mức hằng ngày được chia sẻ trên tất cả các khoá của bạn, tính theo tài khoản.
4Thu hồi và luân chuyển khoá
Nếu một khoá bị lộ — commit vào một kho lưu trữ, dán vào một cuộc chat, hoặc rò rỉ theo bất kỳ cách nào khác — hãy thu hồi nó ngay lập tức từ bảng điều khiển của bạn. Việc thu hồi có hiệu lực ngay: khoá bị thu hồi ngừng hoạt động trong vài giây, không phải sau một độ trễ nào đó.
Vì hạn mức hằng ngày được chia sẻ theo tài khoản, việc thu hồi một khoá không đặt lại bộ đếm sử dụng của bạn. Luân chuyển khoá thường xuyên là một thói quen tốt: tạo khoá mới, triển khai nó vào dịch vụ của bạn, xác nhận nó hoạt động, rồi thu hồi khoá cũ để không có thời gian gián đoạn.
- Thu hồi một khoá từ bảng điều khiển của bạn; nó ngừng hoạt động gần như ngay lập tức.
- Tạo khoá thay thế trước, triển khai nó, rồi thu hồi khoá cũ để luân chuyển không gián đoạn.
- Thu hồi một khoá không đặt lại hạn mức hằng ngày của bạn — nó đặt lại vào nửa đêm UTC.
5Các lỗi xác thực
Một khoá thiếu, sai định dạng, hoặc đã bị thu hồi trả về 401 kèm một mã lỗi máy-đọc-được và một thông điệp người-đọc-được. Nếu các yêu cầu của bạn đột nhiên bắt đầu thất bại với 401, hãy kiểm tra rằng khoá chưa bị thu hồi và rằng header Authorization được viết chính xác là Bearer cộng một dấu cách cộng khoá.
Một khoá hợp lệ nhắm tới một nhóm bạn không quản lý trả về 404. Một khoá hợp lệ trên một gói dưới Pro gọi một endpoint chỉ-dành-cho-Pro trả về 403 với mã plan_required và một gợi ý nâng cấp.
- 401 — khoá bị thiếu, sai định dạng, hoặc đã bị thu hồi.
- 404 — nhóm mục tiêu không tồn tại hoặc bạn không phải quản trị viên của nó.
- 403 plan_required — endpoint cần gói Pro trở lên trên nhóm đó.