HHarperHarbor
控制台

Open API v1

快速開始

這份指南說明 Open API v1 的 OAuth 流程。首次接入請先申請應用，再依接入設定完成註冊、授權與 API 呼叫。

申請接入

  1. 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. 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. 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. 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" }

請求標頭

AuthorizationBearer <access token>
languagezh-Hant · zh-Hans · en · ja · ko
fromweb (選填)

錯誤

錯誤回應為 JSON，包含錯誤代碼、訊息與是否可重試。收到 401 時，先嘗試更新 token；若仍無法通過驗證，再請用戶重新授權。

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

配額

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

閱讀 API 規格 →