產生 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

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

Last updated