動態請求簽名

所有 API 請求須包含 JWT 令牌，

JWT 令牌

請使用 Bearer schema 格式，在 HTTP request header 的 Authorization 標頭中傳遞 JWT 令牌。

Authorization: Bearer <JWT令牌>

參考連結:

JWT headers

JWT header 是 JWT 令牌的一個部分，該部分是一個 JSON 對象，其中包含描述該 JWT 的元數據。JWT headers 通過 Base64 編碼並放置在 JWT 令牌的開頭。

JWT headers 包括以下字段：

範例：

{
  "alg": "EdDSA",
  "kid": "ba240452-7fa7-49e9-884b-58b90b9c544e"
}

JWT payload

JWT payload 是 JWT 令牌的另一個部分，該部分也是一個 JSON 對象，包含聲明和元數據。JWT payload 通過 Base64 編碼並放置在 JWT headers 和 JWT signature 之間。

claims	說明
iat	簽發時間戳，指定 JWT 的發行時間，以 Unix 時間表示
aud	請求目標，固定為 public-api-v2
jti	用於防止重放攻擊，一個短時間內不會重複的字符串，推薦使用 UUIDv4
path	請求路徑，如/api/v2/example
method	請求方法(大寫)，如 POST
bodyHash	請求 body 的 sha256 hash 值，如果是 GET 請求，則不會驗證此 claim

假定請求的 body 為{"foo":"bar"}，則 bodyHash 的值為7a38bf81f383f69433ad6e900d35b3e2385593f76a7b7ab5d4355b8ba41ee24b。

範例:

{
  "iat": 1672502400,
  "aud": "public-api-v2",
  "jti": "6e014086-835b-42d5-93a7-a85373b26ed6",
  "path": "/api/v2/example",
  "method": "POST",
  "bodyHash": "7a38bf81f383f69433ad6e900d35b3e2385593f76a7b7ab5d4355b8ba41ee24b"
}

JWT signature

JWT signature 部分是由前兩個部分 header 和 payload 結合起來，再用私鑰進行簽名後得到的。

JWT 完整格式

最終的 JWT 令牌由三部分組成，每一部分都經過 Base64 編碼並用 . 分隔，使用在後台訪問令牌頁面選擇的算法加密。格式如下

Authorization: Bearer 簽名算法(base64(Jwt_header) + "." + base64(Jwt_payload) + "." + base64(Jwt_signature))

產生令牌後放入請求的 header 即可

POST /api/endpoint HTTP/1.1
Host: example.com
Authorization: Bearer eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJzdWIiOiAiMTIzNDU2Nzg5MCIsICJuYW1lIjogIkpvaG4gRG9lIiwgImlhdCI6IDE1MTYyMzkwMjJ9.uDmtOGz4_rQJHZTp7aeIzpgymLe0P6E9oU_JKo2-LUk  // [!code focus]
Content-Type: application/json

{
  "some": "data"
}

JWT 範例

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "afe62597-4cd8-4ad2-a012-deb2327e5712"
}

Payload

{
  "aud": "public-api-v2",
  "iat": 1516239022,
  "jti": "29167995-3483-458d-82d0-842a867e2ec6"
}

Private Key (私鑰)

Public Key (公鑰)

最終 Jwt

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImFmZTYyNTk3LTRjZDgtNGFkMi1hMDEyLWRlYjIzMjdlNTcxMiJ9.eyJhdWQiOiJwdWJsaWMtYXBpLXYyIiwiaWF0IjoxNTE2MjM5MDIyLCJqdGkiOiIyOTE2Nzk5NS0zNDgzLTQ1OGQtODJkMC04NDJhODY3ZTJlYzYifQ.TfJk91TB1zwuAtNYPtjOsCeHcKIJYp6uvm-HqehkFJ49W8E2Ve8IAFYLW3n5zqro1b_M2Q2vsSFQzOFstxWv3qbJw6e3MHlcjoMHqK9UaUeSL4qLpyWMsGA45wqXljIOUzy8HGyu7pX9LV5k2PSH0BTakv_63_QD-QokHgcE7uGe3c2bm78crgg5WCZzguzgTscMIcoDT0DanQn2ALgTs-1fhx1Ql-dr6qYfpBjR8YsCkcIbQEo2lwVsGLx3uZK_mZYCBQWuBYNuG37cVG8ndgSiit6KuuQ6VYuU7Uh3mQ_jNTIOBup14ObJPexCU5caFdhaDd_c4Hx0P1ATDQfwdQ

JWT 產生範例

常見問題 (FAQ)

為何送出的 JWT 令牌錯誤？

請確認送出的 JWT（JSON Web Token） 格式是否正確。
JWT 應為一個字串，由三個部分組成，並以 "." 串接。

正確格式範例：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

若確認格式正確，但仍遇到問題，請在 群組內向我方技術團隊回報。

JWT 所需的私鑰該如何獲取？

私鑰（Private Key） 可在後台 訪問令牌管理頁面 創建令牌後獲取。