Authentication

Every request to /open/v1 carries a Bearer access token. Tokens come from the platform’s OAuth 2.1 server; there are no API keys for user-scoped calls and no cookies.

Two identities

Who	Credential	Represents
A person using your app	OAuth access token (authorization code + PKCE)	The user, with your app’s client_id attached
Your server	App API key (issued in the developer console)	Your app itself — server-to-server calls such as reading usage

User tokens are what the conversation and card endpoints expect. When a user first authorizes your app, the platform adds them to the app’s user list in the developer console.

Registration

Register once per origin with POST /oauth/register. Rules:

• redirect_uris must be https, except http://localhost and loopback IPs during development.
• A redirect URI must not contain a fragment. Use history routing, not hash routing, for the callback page.
• Persist the returned client_id keyed by origin. Registering again creates another client.

Authorization

Send the browser to /oauth/authorize with response_type=code, your client_id, the redirect_uri, a state, a PKCE code_challenge (S256) and resource=https://api.harperharbor.com/open/v1.

Full-page navigation

The authorize step must go to the absolute API origin. A proxied fetch would follow the server’s redirect to the sign-in page and return its HTML, breaking the flow.

The server signs the user in, asks for consent, and redirects back with ?code=…&state=…. Verify state before exchanging the code.

Token exchange and refresh

POST /oauth/token with grant_type=authorization_code, the code, client_id, redirect_uri, code_verifier and the same resource. You receive access_token, refresh_token and expires_in.

Refresh with grant_type=refresh_token. A 401 response means authentication failed. Try refreshing the token. If refresh also fails, ask the user to authorize again.

Scopes

Phase 1 issues one scope, mcp:card-writer, which covers play and authoring for the signed-in user. Finer scopes are on the roadmap; an older client that keeps requesting this scope keeps working.

Revocation

A user can revoke your app from their account page at any time. Existing tokens stop working immediately; your next call returns 401. Handle it like an expired token: try to refresh, then send the user back through authorization.