快速开始

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

商户接入 · OAuth

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

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