驗證機制 (Authorization)

API Key 與 Secrey Key

註冊完 Recommend HQ 後，使用者會得到一組 API_KEY 與 SECRET_KEY：

• API_KEY: 作為使用者的身份識別。
• SECRET_KEY: 用來簽身份驗證用的 HTTP Header。

HTTP Header

所有的API呼叫都必須在 HTTP Header 中提供以下欄位做驗證：

APIKey

例如：

APIKey: {API_KEY}

請將 {API_KEY} 替換成 API_KEY 實際內容。

Authorization

例如：

Authorization: Bearer {TOKEN}

其中 {TOKEN} 可參考 JSON Web Token，由三個部分組成：

HEADER

固定為

{
  "alg": "HS256"
}

做 base64UrlEncode

PAYLOAD

須提供以下資訊：

• scopes: 為一個陣列，列出所有授權之API路徑
• iat：TOKEN發放時的 unix timestamp

例如：

{
  "scopes": ["/list-projects", "/get-project"],
  "iat": 1624349717
}

做 base64UrlEncode

則該 TOKEN 僅在接近 1624349717 這個時間的一定時間內，對 /list-projects 和 /get-project 這兩隻 API 有效。

SIGNATURE

使用 SECRET KEY 對上面的 HEADER 與 PAYLOAD 做以下組合：

HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  {SECRET_KEY}
)

此組合可使用任何JWT的程式庫完成，例如：PyJWT。測試時也可以使用 JSON Web Token 提供的網頁介面產生。

範例

產生 HTTP Header

安裝 pyjwt 套件

python

import jwt
import time

JWT_ALGORITHM = "HS256"

def create_headers(scopes):
    payload = {
        "scopes": scopes,
        "iat": int(time.time()),
    }
    token = jwt.encode(payload, "$SECRET_KEY", algorithm=JWT_ALGORITHM)

    headers = {
        "Authorization": f"Bearer {token}",
        "APIKey": "$API_KEY",
        "Content-Type": "application/json"
    }

    return headers

呼叫 API

curl

curl --request GET 'http://api.raas.kklab.com/list-projects' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZXMiOlsiL2xpc3QtcHJvamVjdHMiXSwiaWF0IjoxNjI0MzQ5NzE3fQ.0fGy-BZVM_If8OTYF6hAbojlok3xi4Oy9SbT3UCQH2Q' \
--header 'APIKey: THTIfPMmHAoYFD2bmuDt'

python

import requests
from pprint import pprint

headers = create_headers(scopes=["/list-projects"])

url = "https://api.raas.kklab.com/list-projects"

response = requests.request("GET", url, headers=headers)

pprint(response.json())

該 API 會回傳目前帳號下的所有專案。