API Keys
Cách tạo, quản lý và sử dụng API key để truy cập lập trình vào REST API của VergeOS, bao gồm xác thực, kiểm soát truy cập IP, cài đặt hết hạn và các thực hành bảo mật tốt nhất.
Tổng quan
Khóa API cung cấp xác thực cho truy cập theo chương trình vào VergeOS REST API và các dịch vụ tích hợp. Mỗi khóa API được gắn với một tài khoản người dùng cụ thể và kế thừa quyền cũng như mức truy cập của người dùng đó. Điều này cho phép các ứng dụng, script và công cụ bên thứ ba tương tác với VergeOS mà không cần các phiên đăng nhập tương tác.
Các mục đích sử dụng phổ biến của khóa API:
Xác thực REST API cho tự động hóa và tích hợp
Truy cập bộ định tuyến AI tương thích với OpenAI
Tích hợp công cụ bên thứ ba (giám sát, điều phối, công cụ IaC)
Xác thực pipeline CI/CD
Hiểu về Xác thực Khóa API
Khóa API trong VergeOS hoạt động như các token Bearer trong header HTTP Authorization. Không giống như token phiên được tạo trong khi đăng nhập giao diện người dùng (vốn hết hạn sau thời gian không hoạt động), khóa API vẫn hợp lệ cho đến ngày hết hạn được cấu hình hoặc khi bị xóa thủ công.
Mỗi khóa API kế thừa tất cả quyền từ tài khoản người dùng được liên kết. Một khóa API được tạo cho người dùng Tenant Admin sẽ có đặc quyền Tenant Admin, trong khi khóa dành cho System Admin sẽ có quyền truy cập toàn hệ thống.
Tạo khóa API
Đi tới Quản lý Khóa API
Từ menu chính của VergeOS, đi tới Hệ thống > Người dùng
Chọn tài khoản người dùng sẽ sở hữu khóa API
Trong bảng điều khiển người dùng, nhấp vào API Keys tiện ích để xem các khóa hiện có
Phần Khóa API hiển thị một bảng với:
Tên: Định danh mô tả cho mỗi khóa
Lần đăng nhập gần nhất: Dấu thời gian xác thực gần nhất
IP lần đăng nhập gần nhất: IP nguồn của lần xác thực gần nhất
Hết hạn: Số ngày còn lại đến khi hết hạn
Đã tạo: Dấu thời gian tạo khóa
Tạo Khóa API Mới
Nhấp + Khóa API Mới ở cuối bảng Khóa API
Biểu mẫu mở ra với hai bảng: Khóa API (bên trái) và Truy cập (bên phải)
Cấu hình Cài đặt Khóa API
Tên (Bắt buộc) Nhập một định danh mô tả cho khóa API. Đặt tên rõ ràng giúp theo dõi và quản lý khóa tốt hơn.
Mô tả (Tùy chọn) Thêm ngữ cảnh bổ sung về mục đích của khóa, người yêu cầu hoặc các hệ thống liên quan.
Loại hết hạn Chọn cách quản lý thời hạn hiệu lực của khóa:
Đặt ngày: Xác định ngày hết hạn cụ thể (khuyến nghị vì bảo mật)
Không bao giờ hết hạn: Tạo khóa vĩnh viễn (sử dụng thận trọng)
Hết hạn (Khi chọn "Đặt ngày") Sử dụng bộ chọn ngày/giờ để đặt thời điểm khóa sẽ hết hạn. Các khoảng hết hạn phổ biến là 30, 60 hoặc 90 ngày.
Cấu hình Kiểm soát Truy cập
Danh sách Cho phép IP Hạn chế khóa API đối với các địa chỉ IP hoặc phạm vi CIDR cụ thể. Chỉ các địa chỉ được liệt kê mới có thể xác thực bằng khóa này.
Nhấp + (dấu cộng) biểu tượng để thêm một mục
Nhập một địa chỉ IP (ví dụ,
192.168.1.100) hoặc phạm vi CIDR (ví dụ,192.168.1.0/24)Đánh dấu ô chọn để bật mục
Thêm các mục bổ sung khi cần
Danh sách Chặn IP Chặn các địa chỉ IP hoặc phạm vi cụ thể sử dụng khóa này, đồng thời cho phép tất cả các địa chỉ khác.
Nhấp + (dấu cộng) biểu tượng để thêm một mục
Nhập địa chỉ IP hoặc phạm vi CIDR để chặn
Đánh dấu ô chọn để bật mục
Lưu và Lấy Khóa API
Rà soát tất cả cài đặt để đảm bảo chính xác
Nhấp Gửi để tạo khóa API
Một cửa sổ bật lên hiển thị khóa API được tạo với hai tùy chọn:
Sao chép: Nhấp để sao chép toàn bộ chuỗi khóa vào clipboard của bạn
Lưu: Nhấp để tải xuống khóa dưới dạng tệp
.PAK(tệp Khóa API được bảo vệ)
Hiển thị một lần
Khóa API đầy đủ chỉ được hiển thị tại thời điểm tạo. Khi bạn đóng cửa sổ bật lên này, không thể truy xuất lại khóa đầy đủ. Nếu bạn làm mất khóa, bạn phải xóa nó và tạo một khóa mới.
Sau khi bảo vệ khóa, đóng cửa sổ bật lên. Khóa API mới sẽ xuất hiện trong bảng Khóa API.
Quản lý Các Khóa API Hiện Có
Chỉnh sửa Khóa API
Trong bảng Khóa API, tìm khóa bạn muốn sửa đổi
Nhấp Chỉnh sửa (biểu tượng bút chì) bên cạnh tên khóa
Cập nhật các cài đặt (tên, mô tả, thời hạn hết hạn, danh sách IP)
Nhấp Gửi để lưu thay đổi
Xóa Khóa API
Trong bảng Khóa API, tìm khóa bạn muốn xóa
Nhấp Xóa (biểu tượng thùng rác) bên cạnh tên khóa
Xác nhận việc xóa
Thu hồi ngay lập tức
Xóa một khóa API sẽ ngay lập tức thu hồi toàn bộ quyền truy cập. Bất kỳ ứng dụng hoặc script nào sử dụng khóa đã xóa sẽ không thể xác thực.
Sử dụng Khóa API
Định dạng Xác thực
Khóa API được dùng trong header HTTP Authorization dưới dạng token Bearer:
Yêu cầu API Ví dụ
Lưu Trữ Biến Môi Trường
Vì lý do bảo mật, hãy tải khóa API từ các biến môi trường thay vì mã hóa cứng chúng:
Các Lưu Ý Bảo Mật
Xử lý Khóa API Như Mật Khẩu Khóa API cung cấp xác thực đầy đủ với tư cách người dùng được liên kết. Hãy bảo vệ chúng cẩn thận như mật khẩu.
Sử dụng Hạn Chế IP Cấu hình Danh sách Cho phép IP bất cứ khi nào có thể để giới hạn nơi khóa có thể được sử dụng. Điều này giúp giảm đáng kể rủi ro nếu khóa bị xâm phạm.
Đặt Ngày Hết Hạn Tránh dùng khóa vĩnh viễn khi có thể. Việc hết hạn định kỳ buộc phải xoay vòng khóa và giới hạn khoảng thời gian phơi nhiễm.
Theo Dõi Việc Sử Dụng Khóa Thường xuyên xem lại các trường "Lần đăng nhập gần nhất" và "IP lần đăng nhập gần nhất" để xác định các mẫu truy cập bất thường.
Xóa Các Khóa Không Dùng Loại bỏ các khóa API không còn cần thiết để giảm thiểu bề mặt tấn công của bạn.
Khắc phục sự cố
Xác thực Khóa API Thất Bại
Xác minh rằng khóa được đưa vào đúng cách trong header Authorization dưới dạng token Bearer. Kiểm tra xem có khoảng trắng thừa hoặc bị cắt ngắn không.
Từ Chối Truy Cập dù Có Khóa Hợp Lệ
Kiểm tra danh sách Cho phép/Chặn IP. IP nguồn của bạn có thể không được phép hoặc có thể nằm trong danh sách Chặn.
Khóa Đã Hết Hạn
Kiểm tra cột "Hết hạn" trong bảng Khóa API. Tạo một khóa mới nếu khóa cũ đã hết hạn.
Không Thể Khôi Phục Khóa Bị Mất
Không thể khôi phục khóa API sau khi đóng cửa sổ bật lên tạo ban đầu. Hãy xóa khóa bị mất và tạo một khóa mới.
Tài Nguyên Liên Quan
Tài liệu VergeOS REST API - Tài liệu tham khảo API đầy đủ và các endpoint
Cập nhật lần cuối
Nội dung này có hữu ích không?