產生 Headers

簽名

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

標頭

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

header 屬性	類型	說明	如何取得
x-qubic-api-key	string	API KEY	聯絡 Qubic 團隊
x-qubic-ts	string	運算當下的時間戳記	Date.now().toString()
x-qubic-sign	string	運算後的簽名	範例
Authorization	string	選填，使用 Storefront API 存取授權資料時，需要提供此資訊	範例

產生 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. 可以先試著寫單機版程式驗證簽名是否正確