Quickstart

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

Merchant integration · OAuth

1. 1 · Register your client

   Register once per origin. Redirect URIs must be https (localhost is allowed in development) and must not contain a fragment. Persist the returned 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 · Ask the user to authorize

   Authorization code with PKCE (S256). Include the resource indicator so the token is bound to the Open API audience.

   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 · Exchange the code

   Post the code and verifier to the token endpoint. You receive an access token and a 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 · Make the first call

   Use a Bearer token in the Authorization header and include the language header. Responses use public numeric user IDs, without internal account identifiers.

   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 }