Quickstart

Use your own account

You can register directly without joining a merchant. Open Personal API keys, sign in or create an account, and create a key with profile.read permission. Copy the key when it appears; it is shown only once. Keep it private and use it in your local environment or server.

curl https://api.harperharbor.com/open/v1/me \
  -H "Authorization: Bearer $API_KEY" \
  -H "language: en"

Personal keys act as you. Select only the permissions your tool needs: profile.read, role.read, role.write or chat.play. They do not grant console administration access. See Authentication for key expiry and revocation.

Build an app for other users

Use OAuth so each user can authorize your app. Do not ask users to share personal API keys. Contact the team about merchant integration to confirm the services and integration settings you need. Then follow this OAuth flow.

1. Register your client — once per origin. Redirect URIs must be https (http://localhost and loopback IPs are 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"] }

2. Send the user to authorize — authorization code with PKCE (S256). Include the resource indicator so the token is bound to the Open API audience. This is a full-page navigation, not XHR.

   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. Exchange the code for 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

4. Make the first call.

   curl

   curl https://api.harperharbor.com/open/v1/me \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -H "language: en"

   TypeScript

   const res = await fetch("https://api.harperharbor.com/open/v1/me", {
     headers: { Authorization: `Bearer ${accessToken}`, language: "en" },
   });
   const me = await res.json(); // { id: 100001, nickname: "Aoi" }

   Python

   import requests
   r = requests.get("https://api.harperharbor.com/open/v1/me",
                    headers={"Authorization": f"Bearer {access_token}", "language": "en"})
   me = r.json()  # public numeric id only

Then use an agent configuration

GET  /open/v1/role/detail?roleId=…          # read the agent configuration
POST /open/v1/conversation/start            # { roleId, greetingIndex? }
POST /open/v1/conversation/ws-ticket        # one-time ticket for the stream

Continue with Conversation loop and Streaming.