Token Tải lên có Chữ ký

Token tải lên có chữ ký là thông tin xác thực có thời hạn được thiết kế cho tải lên phía client. Chúng cho phép trình duyệt và ứng dụng di động tải tệp trực tiếp lên IPFS Ninja mà không cần lộ khóa API.

Quy trình điển hình: máy chủ của bạn tạo token có chữ ký bằng khóa API, chuyển cho client, và client sử dụng nó để tải tệp. Token tự động hết hạn sau khoảng thời gian đã chỉ định.

Tạo Token có Chữ ký

POST /upload/signed-url

Tạo token tải lên có chữ ký mới.

Tham số	Kiểu	Bắt buộc	Mô tả
name	string	Không	Nhãn cho token (ví dụ: "Tải lên ứng dụng di động").
expiresIn	number	Có	Thời gian sống token tính bằng giây.

Ví dụ yêu cầu

curl -X POST https://api.ipfs.ninja/upload/signed-url \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Mobile app", "expiresIn": 3600}'

Phản hồi 201 Created

{
  "token": "sup_a1b2c3d4e5f6789012345678abcdef01...",
  "tokenId": "tok_9876543210abcdef",
  "tokenPrefix": "sup_a1b2c3d4",
  "tokenName": "Mobile app",
  "expiresAt": 1711040400000
}

WARNING

Token đầy đủ chỉ được trả về một lần khi tạo. Lưu trữ an toàn hoặc chuyển trực tiếp cho client.

Liệt kê Token có Chữ ký

GET /signed-tokens

Trả về tất cả token có chữ ký cho tài khoản, bao gồm thống kê sử dụng.

Ví dụ yêu cầu

curl https://api.ipfs.ninja/signed-tokens \
  -H "X-Api-Key: bws_your_api_key_here"

Phản hồi 200 OK

[
  {
    "tokenId": "tok_9876543210abcdef",
    "tokenPrefix": "sup_a1b2c3d4",
    "tokenName": "Mobile app",
    "expiresAt": 1711040400000,
    "useCount": 15,
    "lastUsedAt": 1711038600000,
    "createdAt": 1711036800000
  }
]

Thu hồi Token có Chữ ký

DELETE /signed-tokens/:tokenId

Thu hồi ngay lập tức một token có chữ ký. Mọi lần tải lên sau đó sử dụng token này sẽ bị từ chối.

Tham số	Kiểu	Bắt buộc	Mô tả
tokenId	string	Có	ID token cần thu hồi (ví dụ: "tok_9876543210abcdef").

Ví dụ yêu cầu

curl -X DELETE https://api.ipfs.ninja/signed-tokens/tok_9876543210abcdef \
  -H "X-Api-Key: bws_your_api_key_here"

Phản hồi 200 OK

{
  "message": "Token revoked"
}

Sử dụng Token có Chữ ký

Để tải lên bằng token có chữ ký, truyền qua tiêu đề Authorization với lược đồ Signed:

curl -X POST https://api.ipfs.ninja/upload/new \
  -H "Authorization: Signed sup_a1b2c3d4e5f6789012345678abcdef01..." \
  -H "Content-Type: application/json" \
  -d '{"content": {"name": "example"}, "description": "Client upload"}'

Nội dung yêu cầu và định dạng phản hồi giống hệt với tải tệp tiêu chuẩn.

Theo dõi Sử dụng

Mỗi khi token có chữ ký được sử dụng, useCount tăng lên và lastUsedAt được cập nhật. Bạn có thể theo dõi hoạt động token qua GET /signed-tokens.

Token có chữ ký được ghi nhận với tiền tố trong trường API_KEY_PREFIX của phân tích. Điều này có nghĩa bạn có thể lọc phân tích theo tiền tố token có chữ ký giống cách lọc theo tiền tố khóa API. Xem Phân tích để biết chi tiết.

Ví dụ: Tải lên từ Trình duyệt

Tạo token trên máy chủ và sử dụng trong JavaScript phía client:

// Phía máy chủ: tạo token có hiệu lực 1 giờ
const res = await fetch("https://api.ipfs.ninja/upload/signed-url", {
  method: "POST",
  headers: {
    "X-Api-Key": "bws_your_server_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ name: "Web form", expiresIn: 3600 })
});
const { token } = await res.json();
// Chuyển `token` cho client

// Phía client: tải tệp bằng token có chữ ký
const file = document.getElementById("fileInput").files[0];
const reader = new FileReader();
reader.onload = async () => {
  const base64 = reader.result.split(",")[1];
  const uploadRes = await fetch("https://api.ipfs.ninja/upload/new", {
    method: "POST",
    headers: {
      "Authorization": `Signed ${token}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      content: base64,
      description: "User upload"
    })
  });
  const data = await uploadRes.json();
  console.log("Uploaded:", data.cid);
};
reader.readAsDataURL(file);