Fastify SDK

Follow the Fastify Quickstart directions to add Hellō to your application in minutes.


Following are the steps required to setup this package:

1. Package Installation

npm i @hellocoop/fastify

Hellō Quickstart will perform steps 2 - 4 for you

npx @hellocoop/quickstart@latest --nextjs


The environment variable HELLO_COOKIE_SECRET must be set to 64 char (32 byte) random hex string is required to encrypt cookies used by this package. This can be in .env for local development.

You can generate new values with:

node -e"console.log(crypto.randomBytes(32).toString('hex'))"

Remember to set a unique HELLO_COOKIE_SECRET in each of your deployed environments.

See Environment Vars for additional values that can be set.

The .env file should not be checked into your repository, and should be in your .gitignore file.

3. client_id

If not using Hellō Quickstart, you will need to create an application at the Hellō Developer Console (opens in a new tab) and get a client_id.

4. hello.config.js

The convention is to create a hello.config.js file in the root of your project for configuration. This file is imported into the hellocoop.js file and passed to the pageAuth() function for configuration. Below is a basic configuration file. See for additional configuration.

const config = {
    client_id: 'your-client_id-here'
module.exports = config

This file should be checked into your repository.

See hello.config.js for additional configuration.

5. API Route

In your main server file add the following code:

helloAuth() will add the /api/hellocoop endpoint which will process login, logout, and the redirect callback.

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



Configures the SDK and adds the /api/hellocoop route. See 5. Api Route for usage.


Decrypts the hellocoop_auth cookie, sets auth to the value, and returns the result. If no cookie, sets auth to:

isLoggedIn: false


Returns the auth object if req.getAuth() has been called, or setAuth Middleware has been processed. Here is an example with the default scopes:

isLoggedIn: true,
sub: '66752aed-9cc2-4d17-875f-379b1a578f9a',
iat: '1699234659',
name: 'Dick Hardt',
picture: '',
email: ''


Clears the hellocoop_auth cookie.


import { redirect, unauthorized, setAuth } from '@hellocoop/fastify/middleware'


Will redirect to the passed path if isLoggedIn=false.




Will return a 401 status code if isLoggedIn=false


app.register( unauthorized )


Middleware that reads and decrypts the hellocoop_auth cookie and sets req.auth.


app.register( setAuth )