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 (or getAuth), 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.

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. The getAuth operation is an alias for auth.

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)

Required Parameters:

Optional Parameters:

Example:

https://your-app.com/api/hellocoop?op=invite&app_name=MyApp&target_uri=/dashboard&role=user

Error Responses:

• 401 Unauthorized - User not logged in
• 400 Bad Request - Missing required parameters

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:

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:

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 Responses:

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

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

{
  "error": "invalid_request",
  "error_description": "Invalid state parameter"
}

{
  "error": "invalid_client",
  "error_description": "Wrong ID token audience"
}

{
  "error": "invalid_request",
  "error_description": "Wrong nonce in ID token"
}

{
  "error": "invalid_request",
  "error_description": "The ID token has expired"
}

{
  "error": "access_denied",
  "error_description": "loginSync denied access"
}

{
  "error": "server_error",
  "error_description": "Failed to exchange code for tokens"
}

Additional Operations

Protocol Flows

The Hellō Endpoint also handles OpenID Connect protocol flows without the op parameter:

• Authorization Response: When Hellō redirects back with code and state parameters
• IdP Initiated Login: When iss, domain_hint, or login_hint parameters are present
• Wildcard Console: When wildcard_console parameter is present for domain registration

POST Requests

The endpoint also accepts POST requests for:

• Command Processing: When command_token is present in the request body
• Protocol Redirects: When iss, domain_hint, or login_hint are present in POST body

Mobile App Flow

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

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