Use OAuth when another application needs delegated access to HAL.

Use cases

• Third-party products connecting user-owned HAL projects
• Widget hosting services that need to embed HAL on behalf of shared customers
• Delegated access flows where a user explicitly authorizes the integration
• Apps that should not depend on personal session tokens or HAL’s long-lived widget secret

Choose the right integration surface

Public OAuth widget connections

HAL-managed public apps are the default choice when an external backend needs to let many customers connect one HAL project at a time. The granted scope is intentionally narrow: widget:serve.

After the user approves the connection, the external backend receives an access token and refresh token. It can use that access token to ask HAL to sign widget identities without ever learning the project’s permanent identity_secret.

Flow

1. Redirect the user to HAL’s authorize screen with your client_id, redirect_uri, scope=widget:serve, and the target project_id if you already know it.
2. The user signs in to HAL, chooses the project, and approves the connection.
3. Exchange the returned authorization code at /oauth/token.
4. Call /api/oauth/widget/sign-identity with the returned bearer token whenever you need a user_hash for widget identify().

Token response

The public app token exchange returns:

• access_token
• refresh_token
• token_type = Bearer
• expires_in
• scope = widget:serve
• project_id
• widget_script_url
• api_base_url

Backend example

1. Redirect user to HAL authorize
2. Exchange code at POST /oauth/token
3. Sign identities at POST /api/oauth/widget/sign-identity
4. Pass user_hash into HalWidget.identify({ user_id, user_hash })

Private project OAuth clients

The older project-level OAuth client flow is still supported for private, one-off integrations created directly in HAL project settings. That legacy token exchange returns app_id and widget_secret instead of bearer tokens.

Use the private client flow only when the integration is owned by the same HAL customer and does not need a reusable public app registration.