Express Quickstart

Follow the directions below to add Hellō (opens in a new tab) to your Express (opens in a new tab) application in a couple minutes.

  • You will get the user's name, verified email, and profile picture.
  • Users can use their preferred login provider including Apple, Facebook, Google, GitHub, GitLab, and Microsoft.
  • Hellō has done all the work to get a verified email and profile picture.

Add Hellō to Your Server

Don't have a project? Start with the Express application generator (opens in a new tab).

Install the Package

In your project directory:

npm i @hellocoop/express

Run Quickstart

npx @hellocoop/quickstart@latest --express

Quickstart will prompt you to:

  • download the @hellocoop/quickstart package
  • log in to Quickstart with Hellō
  • create an application, or select an existing one

Quickstart will then:

  • create a hello.config.js file containing your app's client_id
  • generate a random HELLO_COOKIE_SECRET and add it to .env

Mount Hellō

In your main server file add the following code:

Your server should now be fully configured to work with Hellõ

Test Your Server

Start your server. Assuming the server started on port 3000:

  1. Check your logged in status in a new tab with:
    http://localhost:3000/api/hellocoop?op=auth (opens in a new tab)

You should get {"isLoggedIn": false} in your browser window.

  1. Log in to Hellō with in a new tab with:
    http://localhost:3000/api/hellocoop?op=login (opens in a new tab)

  2. See your logged in status and profile by reloading /api/hellocoop?op=auth

You should see something similar to this:

  "isLoggedIn": true,
  "sub": "66752aed-9cc2-4d17-875f-379b1a578f9a",
  "iat": 1699234659,
  "name": "Dick Hardt",
  "picture": "",
  "email": ""
  1. Log out in a new tab with:
    http://localhost:3000/api/hellocoop?op=logout&target_uri=%2Fapi%2Fhellocoop%3Fauth%3Dtrue (opens in a new tab)

After being logged out, you will be redirected back to /api/hellocoop?op=auth to confirm you are logged out.

You have added Hellō to your Express application.

Add a Callback Stub

We will now add a stub function that you can modify later to integrate with your user database.

Create Callback Stub

Copy the following code and save it to hello-callback.js in your root folder (you can move it later):

// hello-callback.js
module.exports = async ({ 
    payload,    // parsed ID Token payload
    token,      // ID Token in compact, unparsed format
    req,        // NextApiRequest
    res         // NextApiResponse
}) => {
    console.log('Callback received:',JSON.stringify(payload,null,4))
    // TODO
    // lookup user from your DB wth payload.sub user identifier
    // create a user in DB if not found if open registration
        // accessDenied = true, // will set auth.isLoggedIn = false
        // isProcessed = true,  // response has been sent by callback()
        // updatedAuth = {},    // auth object stored in cookie

Configure Callback

Add the highlighted lines to your hello.config.js file:

const loggedIn = require('./hello-callback')
const config = {
    client_id: 'YOUR_CLIENT_ID',
    callbacks: {
module.exports = config

Test the Callback

  1. Restart your server for it to load the updated configuration

http://localhost:3000/api/hellocoop?op=login&target_uri=%2Fapi%2Fhellocoop%3Fauth%3Dtrue (opens in a new tab)

You should see the contents of the ID Token payload logged to your terminal. See OpenID Connect | ID Token for details.

You now have a stub you can extend to integrate your user database!

Next Steps

  • Change the claims received or providers recommended by updating your hello.config.js file.

  • Review the SDK Reference | Next.js documentation.

  • Replace the ./hello-callback.js file with your own code that integrates with your user DB.