Open API v1

快速開始

使用自己的帳號呼叫 API，先建立個人 API Key。替使用者提供應用服務，則使用下方的商戶 OAuth 流程。

使用個人 API Key

登入個人控制台，建立具有 profile.read 權限的 API Key，再呼叫下方介面取得自己的帳號資料。金鑰只顯示一次，請妥善保存。

GET https://api.harperharbor.com/open/v1/me
Authorization: Bearer <personal API key>
language: en

商戶接入 · OAuth

1 · 登記你的客戶端

每個來源登記一次。回呼 URI 必須是 https（開發時允許 localhost），且不能帶 fragment。保存回傳的 client_id。

POST https://api.harperharbor.com/oauth/register
Content-Type: application/json

{
  "client_name": "Your app",
  "redirect_uris": ["https://app.example.com/oauth/callback"],
  "grant_types": ["authorization_code", "refresh_token"]
}

→ 201 { "client_id": "…" }

2 · 請用戶授權

授權碼 + PKCE（S256）。帶上 resource 參數，token 才會綁定到開放 API 這個受眾。

https://api.harperharbor.com/oauth/authorize
  ?response_type=code
  &client_id=…
  &redirect_uri=https://app.example.com/oauth/callback
  &resource=https://api.harperharbor.com/open/v1
  &state=…
  &code_challenge=…            # base64url(sha256(verifier))
  &code_challenge_method=S256

3 · 交換授權碼

把 code 與 verifier POST 到 token 端點，拿到 access token 與 refresh token。

POST https://api.harperharbor.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=…&client_id=…
&redirect_uri=…&code_verifier=…&resource=https://api.harperharbor.com/open/v1

→ 200 { "access_token": "…", "refresh_token": "…", "expires_in": 3600 }

4 · 發第一個請求
在 Authorization 標頭使用 Bearer token，並帶上 language 標頭。回應中的用戶 ID 為公開數字 ID，不含內部帳號識別碼。
```
GET https://api.harperharbor.com/open/v1/me
Authorization: Bearer <access token>
language: en

→ 200 { "id": 100001, "nickname": "Aoi" }
```

請求標頭

Authorization	Bearer <access token>
language	zh-Hant · zh-Hans · en · ja · ko
from	web (選填)

錯誤

錯誤回應包含代碼、訊息與是否可重試。個人 API Key 收到 401 時，請檢查金鑰是否過期或已撤銷。OAuth token 可先嘗試更新，失敗時再請使用者授權。

{ "error": "unauthorized | forbidden | not_found | internal",
  "message": "…",
  "retryable": true }

配額

每個應用設有每日 credits 配額，用於限制用量，不另收費。開發者控制台可依應用、服務與線路查看使用情況。

閱讀 API 規格 →