🛠️
Qubic Development Documentation
  • 開始使用
  • Qubic 產品、API 與 SDK 入門
  • 基礎
    • Qubic Connect SDK
      • 安裝
      • 登入
      • 結帳與支付
      • 第三方帳號綁定
      • 在伺服器端驗證登入權限
    • Web3 Qubic SDK
    • 使用 GraphQL
      • 產生 Headers
      • GraphQL 客戶端
  • API
    • 🛒Creator Storefront API
    • ⚗️Creator Admin API
      • 鑄造 NFT
      • 更新 Metadata
      • 取得 Ticket
      • 如何設置預售選項
    • 🎟️Pass Admin API
      • 驗證 NFT 持有者
      • 取得智能合約中的所有 NFT
  • 進階
    • 📏Pass Client Auth API
      • 透過簽名驗證登入
      • 透過 Webhook 驗證身份
Powered by GitBook
On this page
  • 簽名
  • 標頭
  • 標準範例
  • 高安全性的範例
  • 單機版驗證簽名
  • 標準簽名
  • 高安全性的簽名
  • 常見問題

產生 Headers

Last updated 9 months ago

簽名

包含 Creator Storefront / Admin API 以及 Pass Admin API,只要是透過 GraphQL 呼叫的 APIs,都需要使用以下方法產生簽名。

標頭

Creator Admin API、Pass Admin API 以及 Creator Storefront API 要透過 key/secret 取得使用權限,需於通訊時在 header 中加入指定的屬性以完成驗證,描述如下:

header 屬性類型說明如何取得

產生 API Key 時可以選擇是否採用安全性更高的 API 通訊機制,請依照是否有勾選使用對應的 Header 格式。 接下來會提供 標準範例 和 高安全性的範例 msg 的部分,標準不包含 body 本身,而高安全性是有包含的

標準範例

要被簽名的訊息不包含 request body

yarn add graphql-request graphql crypto-js      # yarn
npm install graphql-request graphql crypto-js   # npm
import HmacSHA256 from "crypto-js/hmac-sha256.js";
import Base64 from "crypto-js/enc-base64.js";
import { request, gql } from "graphql-request";

const KEY = "YOUR_CREATOR_ADMIN_API_KEY";
const SECRET = "YOUR_CREATOR_ADMIN_API_SECRET";

const url = "https://creator.qubic.app/admin/graphql";

const urlObj = new URL(url);
const resource = `${urlObj.pathname}${urlObj.search}`; // output: /admin/graphql

const now = Date.now();
const msg = `${now}POST${resource}`;
const sig = HmacSHA256(msg, SECRET).toString(Base64);

const requestHeaders = {
  "x-qubic-api-key": KEY,
  "x-qubic-ts": now.toString(),
  "x-qubic-sign": sig,
};

const document = gql`
  query shop {
    shop {
      id
    }
  }
`;

const result = await request({
  url,
  document,
  requestHeaders,
});

console.log(result);

高安全性的範例

要被簽名的訊息中包含 request body

yarn add graphql-request graphql crypto-js      # yarn
npm install graphql-request graphql crypto-js   # npm
import HmacSHA256 from "crypto-js/hmac-sha256.js";
import Base64 from "crypto-js/enc-base64.js";
import { request, gql, resolveRequestDocument } from "graphql-request";

const KEY = "YOUR_CREATOR_ADMIN_API_KEY";
const SECRET = "YOUR_CREATOR_ADMIN_API_SECRET";

const url = "https://creator.qubic.app/admin/graphql";

const urlObj = new URL(url);
const resource = `${urlObj.pathname}${urlObj.search}`; // output: /admin/graphql

const document = gql`
  query shop {
    shop {
      id
    }
  }
`;

const { operationName, query } = resolveRequestDocument(document);

const body = JSON.stringify({
  query,
  operationName,
});

const now = Date.now();
const msg = `${now}POST${resource}${body}`;
const sig = HmacSHA256(msg, SECRET).toString(Base64);

const requestHeaders = {
  "x-qubic-api-key": KEY,
  "x-qubic-ts": now.toString(),
  "x-qubic-sign": sig,
};

const result = await request({
  url,
  document,
  requestHeaders,
});

console.log(result);

單機版驗證簽名

這邊提供演算法例子,供參考用

標準簽名

yarn add crypto-js      # yarn
npm install crypto-js   # npm
import HmacSHA256 from "crypto-js/hmac-sha256.js";
import Base64 from "crypto-js/enc-base64.js";

function sign(option) {
  const { now, method, resource, secret } = option;

  const msg = `${now}${method}${resource}`;
  const sign = HmacSHA256(msg, secret).toString(Base64);

  return { msg, sign };
}

const { msg, sign } = sign({
  now: 1689907490132,
  method: "POST",
  resource: "/admin/graphql",
  secret: "secret",
});

console.log(msg === "1689907490132POST/admin/graphql"); // true
console.log(sign === "d1tZksk8khiWQ+UTUY7m6u1Msb5Oyhfej+c384e5GM8="); // true

高安全性的簽名

yarn add crypto-js      # yarn
npm install crypto-js   # npm
import HmacSHA256 from "crypto-js/hmac-sha256.js";
import Base64 from "crypto-js/enc-base64.js";

function signSec(option) {
  const { now, body, method, resource, secret } = option;

  const msg = `${now}${method}${resource}${body}`;
  const sign = HmacSHA256(msg, secret).toString(Base64);

  return { msg, sign };
}

const { msg, sign } = signSec({
  now: 1566549227549,
  body: "the_body",
  method: "PUT",
  resource: "/test/path?currency=USD",
  secret: "secret",
});

console.log(msg === "1566549227549PUT/test/path?currency=USDthe_body"); // true
console.log(sign === "xN/7FHzMvIVbJYESYPJlMwNHL9r3DBZ21lsjSn5W3Bo="); // true

常見問題

  • 為何我一直收到 {"error":{"code":404,"message":"resource not found"}}?

    1. 請確認有將 header 所需的資訊放入其中

    2. 請確認正在使用的 API key/secret 與 GraphQL endpoint 是匹配的

    3. 可以先試著寫單機版程式驗證簽名是否正確

x-qubic-api-key

string

API KEY

聯絡 Qubic 團隊

x-qubic-ts

string

運算當下的時間戳記

Date.now().toString()

x-qubic-sign

string

運算後的簽名

範例

Authorization

string

選填,使用 Storefront API 存取授權資料時,需要提供此資訊

範例