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 规格 →