Khóa API và access token

Khóa API là cách chương trình của bạn truy cập API LinkHarbor. Khóa thuộc về một không gian làm việc, không thuộc về một người, và làm được đúng những gì bạn cho phép qua phạm vi. Với các lệnh gọi thực tế, bạn đổi khóa lấy một access token có thời hạn ngắn.

#Ai có thể tạo khóa API?

• Chủ sở hữu và quản trị viên của không gian làm việc – biên tập viên và người xem chỉ thấy thẻ “Ứng dụng đã kết nối” ở “Callback & API”
• Từ gói Creator Pro; ở Creator Free, thẻ ghi “Khóa API có từ gói Creator Pro.”
• Hoạt động cùng lúc: tối đa 5 khóa ở Creator Pro, 20 ở Creator Agency, 50 ở Enterprise

Khi đạt giới hạn, việc tạo khóa thất bại với 409 limit_reached. Hãy xóa trước một khóa không còn cần.

#Tạo khóa API

1. Mở “Callback & API” trong thanh điều hướng
2. Trong thẻ “Khóa API”, nhấp “+ Tạo khóa mới”
3. Ở “Tên (không bắt buộc)”, nhập tên để sau này bạn nhận ra khóa, ví dụ “Pipeline CI/CD” hoặc “Đồng bộ cửa hàng”
4. Ở “Phạm vi”, chọn “Đọc” hoặc “Ghi” cho từng khu vực
5. Nhấp “Tạo khóa”
6. Sao chép ngay “Mã bí mật của khóa (riêng tư)” và cất ở nơi an toàn
7. Đóng hộp thoại – bạn luôn tìm thấy ID khóa trong danh sách

“Tên (không bắt buộc)”

Tối đa 64 ký tự. Không có tên, khóa xuất hiện trong danh sách là “Khóa API #ID”.

“Phạm vi”

Bắt buộc ít nhất một. “Ghi” tự động bao gồm “Đọc” cho cùng khu vực. Thống kê và thanh toán từ người ủng hộ chỉ có quyền đọc, mẫu không gian làm việc chỉ có quyền ghi. Mọi phạm vi được giải thích trong Chi tiết về phạm vi.

“Mã bí mật của khóa (riêng tư)”

Bắt đầu bằng lt_ và chỉ hiển thị đúng một lần (“⚠️ Chỉ hiển thị một lần — hãy sao chép ngay!”). LinkHarbor chỉ lưu hash của nó và không thể cho bạn xem lại sau này.

“ID khóa:”

16 ký tự gồm chữ số và chữ hoa A–F, ví dụ 6F668EA6598B0692. ID không bí mật và xuất hiện trong danh sách kèm nút sao chép.

#Danh sách khóa

Mỗi khóa đang hoạt động hiển thị tên, trạng thái “Hoạt động”, ID khóa, các phạm vi, “Đã tạo:” và “Dùng lần cuối:” hoặc “Chưa từng dùng”. Thời điểm dùng lần cuối được cập nhật ở mỗi lệnh gọi bằng khóa, tối đa một lần mỗi phút. “↺ Làm mới” tải lại danh sách.

#Đổi khóa lấy access token

curl -X POST https://dock.at-harbor.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{"key_id":"6F668EA6598B0692","key_secret":"lt_…"}'

{ "token": "eyJhbGciOiJIUzI1NiIs…", "expires_in": 900 }

token

Access token. Bạn gửi nó với mọi yêu cầu dưới dạng Authorization: Bearer <token>.

expires_in

Thời hạn tính bằng giây: 900, tức 15 phút. Không có refresh token – khi hết hạn, chỉ cần lấy token mới bằng ID khóa và mã bí mật.

Token đại diện cho không gian làm việc và mang đúng các phạm vi của khóa. Nó không có vai trò như một người: các endpoint mà bảng điều khiển dành riêng cho chủ sở hữu và quản trị viên (thành viên, thanh toán, quản lý tên miền, webhook, cài đặt không gian làm việc) luôn từ chối token từ khóa API. Ngoại lệ là liên kết rút gọn và mẫu không gian làm việc, dùng được với phạm vi tương ứng, và việc đọc mã bí mật callback (không có mã bí mật dạng văn bản thuần) với read:workspaces.

#Thử sai và khóa tạm thời

Với api_key_locked, thời gian còn lại nằm trong details.retry_after_sec. Một lần đổi thành công sẽ đặt lại bộ đếm.

#Xóa và thay khóa

1. Nhấp “Xóa” bên cạnh khóa
2. Gõ DELETE để xác nhận
3. Nhấp “Xóa vĩnh viễn”

Khóa ngừng hoạt động ngay lập tức – các access token đã cấp cũng ngừng hoạt động từ thời điểm đó và nhận 401 invalid_token. Không có nút xoay vòng. Để đổi khóa, hãy tạo khóa mới, chuyển chương trình sang khóa đó rồi xóa khóa cũ.

#Khi hạ gói

Nếu không gian làm việc chuyển sang Creator Free, mọi khóa API bị thu hồi. Nếu chuyển sang gói có ít khóa hơn, các khóa mới nhất được giữ và số còn lại bị thu hồi. Khóa đã thu hồi không quay lại sau khi nâng cấp – khi đó bạn tạo khóa mới. Chủ sở hữu nhận email liệt kê các tính năng bị tắt. Xem thêm trong Hủy gói và hạ gói.

#Giữ an toàn

• Chỉ giữ mã bí mật trong trình quản lý secret hoặc biến môi trường, không bao giờ trong mã nguồn hay repository Git
• Không bao giờ dùng nó trong mã chạy trên trình duyệt hay trong ứng dụng trên thiết bị của người dùng
• Tạo một khóa riêng cho mỗi ứng dụng, với càng ít phạm vi càng tốt
• Xóa ngay các khóa không còn cần
• Nếu nghi ngờ bị lộ: hãy xóa khóa và tạo khóa mới