クイックスタート

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

事業者向け連携 · OAuth

1. 1 · クライアントを登録

   オリジンごとに一度登録します。リダイレクト URI は https（開発時は localhost 可）で、フラグメントを含めてはいけません。返された 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 指示子を含めると、トークンがオープン 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 · コードを交換

   コードと verifier をトークンエンドポイントに POST。アクセストークンとリフレッシュトークンを受け取ります。

   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 トークンを設定し、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 }