Two ways to connect, one token endpoint.

Pick the right integration surface

• Public API + API key — you are the HAL customer automating your own workspace. No OAuth needed.
• MCP — AI agents and coding tools reading/acting on HAL data. No OAuth needed.
• OAuth — other people's software connecting to other people's HAL accounts. You're building an integration for distribution.

Public widget app installs

Public apps are project-scoped and grant widget:serve only — enough to serve and identify the widget on the customer's site, nothing more. The flow:

1. Your app initiates authorization for the customer's project.
2. The customer approves the install in HAL's authorize screen (client metadata loads via GET /api/oauth/client?client_id=…).
3. Exchange the code at the token endpoint.

POST /oauth/token

{
  "access_token": "…",
  "refresh_token": "…",
  "project_id": "…",
  "widget_script_url": "https://api.chatwithhal.com/widget.js",
  "api_base_url": "https://api.chatwithhal.com"
}

The response carries everything an embed needs — script URL and API base included — so your installer can complete without further configuration.

Legacy private clients

Project-owned private clients remain available for first-party, one-off integrations. Managed under the project (list, create, delete), their token response returns app_id and widget_secret for direct widget provisioning.

Managing installs

GET    /api/projects/{id}/oauth-clients             # private clients
POST   /api/projects/{id}/oauth-clients
DELETE /api/projects/{id}/oauth-clients/{clientId}

GET    /api/projects/{id}/oauth-connections         # public installs
DELETE /api/projects/{id}/oauth-connections/{id}    # revoke

Handling identities in installed widgets

Widget connections that identify visitors should sign identities — POST /api/oauth/widget/sign-identity issues the HMAC using HAL-held per-install credentials, so your integration server never needs the customer's identity secret. See identity verification.