Khóa API

Khóa API cho phép bạn truy cập REST API của badges.ninja theo cách lập trình. Hãy dùng chúng để tự động hóa việc tạo, cấp và quản lý huy hiệu từ các ứng dụng của bạn.

Tạo khóa API

1. Mở trang API Keys từ thanh bên.
2. Nhấp Create API Key. Một biểu mẫu nội tuyến sẽ mở ra:

3. Đặt tên cho khóa và nhấp Create. Khóa đầy đủ chỉ được hiển thị một lần trên một biểu ngữ màu xanh lá:

4. Hãy sao chép khóa ngay lập tức — khóa đầy đủ chỉ được hiển thị một lần. Nếu bạn làm mất, bạn sẽ cần tạo khóa mới. Sau khi bạn đóng biểu ngữ, bảng điều khiển chỉ hiển thị tiền tố của khóa (ví dụ bws_a1b2c3d4...); khóa đầy đủ vẫn được lưu trên máy chủ để xác thực các yêu cầu của bạn:

Mỗi hàng cũng cho biết thời điểm khóa được tạo và, sau khi khóa được dùng, một dấu thời gian last used để bạn nhận ra các khóa không còn dùng.

Phạm vi truy cập

Khi tạo khóa, bạn có thể đặt khóa ở chế độ chỉ đọc hoặc giữ toàn quyền truy cập:

Phạm vi	Cho phép
Toàn quyền truy cập (mặc định)	Đọc và ghi — liệt kê dữ liệu, cũng như tạo, cấp, cập nhật hoặc xóa.
Chỉ đọc	Chỉ các yêu cầu GET an toàn. Mọi yêu cầu làm thay đổi dữ liệu (POST, PUT, PATCH, DELETE) đều bị từ chối với 403 Forbidden.

Hãy dùng khóa chỉ đọc cho các tích hợp chỉ cần đọc dữ liệu của bạn (báo cáo, bảng điều khiển, sao lưu) để khóa bị lộ cũng không thể thay đổi bất cứ điều gì. Đánh dấu Read-only key trong biểu mẫu tạo; các khóa chỉ đọc hiển thị nhãn Read-only trong danh sách. Các khóa được tạo trước khi có phạm vi truy cập vẫn giữ toàn quyền truy cập.

Định dạng khóa

Khóa API dùng tiền tố bws_ theo sau là chuỗi thập lục phân gồm 32 ký tự:

bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Sử dụng khóa API trong yêu cầu

Thêm khóa API vào header X-Api-Key của mọi yêu cầu API:

curl -X GET https://api.badges.ninja/issuers \
  -H "X-Api-Key: bws_your_api_key_here"

Xem trang Xác thực để biết đầy đủ chi tiết về xác thực API.

Giới hạn khóa theo gói

Số lượng khóa API bạn có thể tạo phụ thuộc vào gói của bạn:

Gói	Giới hạn khóa API
Free	1
Starter ($9/mo)	5
Pro ($29/mo)	20

Thời hạn của khóa

Mọi khóa API hết hạn sau một năm kể từ khi được tạo. Khi khóa hết hạn, nó sẽ ngừng xác thực yêu cầu, giống như thể nó đã bị xóa. Hãy tạo khóa mới trước khi khóa cũ hết hạn để tránh gián đoạn.

Xóa khóa

1. Mở trang API Keys.
2. Tìm khóa bạn muốn xóa.
3. Nhấp Delete.
4. Xác nhận việc xóa.

Sau khi xóa, khóa ngừng hoạt động ngay lập tức. Mọi ứng dụng đang dùng khóa đó sẽ nhận lỗi xác thực.