Web Client API

The Web Client API abstracts logging into Hellō with web applications. The Express, Fastify, and Next.js SDKs all expose the Web Client API through the Hellō Endpoint. It is usually mounted at /api/hellocoop, but can be mounted at any route. Set the API_ROUTE environment variable to this value.

The Hellō Endpoint is also the OpenID Connect redirect_uri for your application. IE, this is where Hellō sends the authorization response. The response is processed by endpoint and an encrypted cookie is set containing the auth state.

Operations

The op query parameter is passed to the Hellō Endpoint to indicate the operation to be performed. Valid values are login, auth, logout, invite, loginURL, and exchange.

Login

Load this endpoint in the browser to login the user. Loading this endpoint will create and load an authorization request to the Hellō Wallet. The authorization response will be sent to the Hellō Endpoint and processed. If successful, the optional loginSync function will be called, and then the browser will be redirected to the target_uri if provided, the route.loggedIn value in hello.config.js, or the / route.

Optional Parameter	Description
`target_uri`	overrides where the user will be redirected to after a successful login.
`scope`	overrides the default scope to request from Hellō.
`login_hint`	provide a login_hint of which user to log in. Set to the user's email address.
`domain_hint`	provide a domain_hint of the domain the user will log in at.
`provider_hint`	overrides the default provider_hint of which providers to show a new user.
`prompt`	- `login` will require a fresh login for the user. - `consent` will present the user with the consent screen. Allows user to update their profile.

Example:

https://your-app.com/api/hellocoop
?op=login
&target_uri=/profile
&scope=profile+nickname
&provider_hint=github+gitlab

Error Response

If there is an error response from Hello, the browser will be redirected to the error page with the error parameter. See Error Response for details on error response values. See hello.config.js for overriding the default error page.

Auth

This operation is to be called by your app and returns a JSON object containing the auth object in the encrypted cookie.

Example:

https://your-app.com/api/hellocoop?op=auth

Logged In Example Response:

{
  "isLoggedIn": true,
  "sub": "sub_vvCgtpv35lDgQpHtxmpvmnxK_2nZ",
  "iat": 1699234659,
  "name": "Dick Hardt",
  "picture": "https://pictures.hello.coop/r/7a160eed-46bf-48e2-a909-161745535895.png",
  "email": "dick.hardt@hello.coop"
}

Logged Out Example Response:

{
  "isLoggedIn":false
}

Logout

Logs out the user by clearing the cookies and calling the optional logoutSync, and then redirects to the logged out route.

Example:

https://your-app.com/api/hellocoop?op=logout

Invite

Starts an invite flow to https://wallet.hello.coop/invite. See Invite API (BETA)

Example:

https://your-app.com/api/hellocoop?op=invite

LoginURL

Returns a login URL and encrypted state for mobile applications or custom authentication flows. This operation is designed for applications that need to handle the authentication flow programmatically rather than through browser redirects.

Example:

https://your-app.com/api/hellocoop?op=loginURL

Optional Parameters:

Parameter	Description
`target_uri`	where the user will be redirected to after a successful login
`scope`	overrides the default scope to request from Hellō
`login_hint`	provide a login hint of which user to log in (email address)
`domain_hint`	provide a domain hint of the domain the user will log in at
`provider_hint`	overrides the default provider hint of which providers to show
`prompt`	`login` requires fresh login; `consent` shows consent screen
`nonce`	optional nonce value for the request
`redirect_uri`	overrides the default redirect URI

Success Response:

{
  "url": "https://wallet.hello.coop/authorize?client_id=...&redirect_uri=...&scope=...&response_type=code&state=...",
  "state": "encrypted_state_value"
}

Error Response:

{
  "error": "server_error",
  "error_description": "Missing HELLO_CLIENT_ID configuration"
}

Exchange

Exchanges an authorization code and state for user authentication data. This operation is typically used by mobile applications or custom authentication flows after receiving the authorization response from the loginURL flow.

Example:

https://your-app.com/api/hellocoop?op=exchange&code=auth_code&state=encrypted_state

Required Parameters:

Parameter	Description
`code`	the authorization code received from Hellō
`state`	the encrypted state value from the loginURL response

Success Response:

{
  "access_token": "encrypted_access_token",
  "auth": {
    "isLoggedIn": true,
    "sub": "sub_vvCgtpv35lDgQpHtxmpvmnxK_2nZ",
    "iat": 1699234659,
    "name": "Dick Hardt",
    "picture": "https://pictures.hello.coop/r/7a160eed-46bf-48e2-a909-161745535895.png",
    "email": "dick.hardt@hello.coop"
  }
}

Error Response:

{
  "error": "invalid_request",
  "error_description": "Missing code parameter"
}

Mobile App Flow

The loginURL and exchange operations work together to enable authentication in mobile applications:

Request Login URL: Call op=loginURL to get the authorization URL and encrypted state
User Authorization: Present the authorization URL to the user (e.g., in a web view)
Handle Redirect: Capture the authorization response containing the code parameter
Exchange Code: Call op=exchange with the code and state to get user authentication data
Store Access Token: Use the returned access_token for subsequent authenticated requests

API References Wallet