Documentation
Invite (BETA)

Invite API (BETA)

⚠️

This feature is currently in BETA, particularly the Multi Tenant/Role features.

Overview

A common feature of applications is to enable your users to invite other users to your application. Managing the links, emails, and status of an invite is undifferentiated work, particularly in a multi tenant / multi role application. Hellō Invite is a free service that lets your users invite other users to your application via an email address. Here is how it works:

  1. You present your user with a button / link to invite other users to your app.

  2. You redirect the user (inviter) to https://wallet.hello.coop/invite with query parameters as described below.

  3. The inviter provides Hellō with the email addresses of the invitees and sends the invites. They can resend or revoke previous invites here as well. In the future Hellō will let a user use their address book.

  4. Hellō sends the invitees invitations to your app via email, with options to accept or decline the invitation.

  5. The invitee accepts the invitation, is redirected to your app's provider initiated login endpoint, where your app then starts a login flow with Hellō.

  6. Your new user completes logging into your application.

You can experience Hellō Invite in the Hellō Playground (opens in a new tab) by inviting others to the Playground once you have logged in, and in the Hellō Developer Console (opens in a new tab) by inviting others to be members of your team / publisher.

Using Hellō Invite

Prerequisites

To use Hellō Invite:

You will also need an events_uri and the ability to process incoming events if you have a multi-tenant or you want to enable the invitee to specify which role the invitee will get in a multi-role application. See Multi-tenant/Multi-role below for details.

Invite Request

Redirect the inviter to https://wallet.hello.coop/invite with the following parameters:

Required Parameters

NameDescription
inviterThe sub provided by Hellō of the inviter.
client_idThe client_id for your application.
initiate_login_uriThe path where the invitee is sent upon accepting the invitation.
return_uriThe URI for Hellō to return the inviter when they are done.

The initiate_login_uri and return_uri must have the same hostname, and that hostname MUST be in one of your application's redirect_uris in the Hellō Developer Console.

See Provider initiated login below for details on the initiate_login_uri.

Example URL

https://wallet.hello.coop/invite
?inviter=59a27193-e919-462b-a324-4158d5ad372d
&client_id=4c1ec93b-2714-4d72-9582-b09c515c5bd8
&initiate_login_uri=https://greenfieldfitness.com/profile
&return_uri=https://greenfieldfitness.com/profile

Optional Parameters

NameDescription
app_nameOverride the name of the app. Defaults to the name registered for the client_id.
promptOverride the prompt string shown to the invitee. Defaults to "name invited you to join app_name" where name is the inviter's name they have provided to your application.

Provider Initiated Login

To use Hellō Invite, you MUST support the provider initiated login flow, also known as Third Party Initiated Login (opens in a new tab).

If you have a B2B application, the provider initiated login flow lets a user access your application from their organization's app portal. In the future, Hellō will let applications that support provider initiated login to log in from their Hellō Wallet.

In this flow, the user starts at Hellō after accepting the invitation, and is redirected to your application with the following query parameters:

NameDescription
isshttps://issuer.hello.coop - the Hellō Issuer
login_hinta value you MUST send back to Hellō

Your application constructs an authorization request the same way as any other authorization request, but you also include the login_hint query parameter as provided.

Managing Invites

You can let your users manage their outstanding invitations with your application by redirecting them to https://wallet.hello.coop/invite with the following parameters:

NameDescription
inviterThe sub provided by Hellō of the inviter
client_idClient ID associated with the app
return_uriThe URI to return the inviter when they are done
manage=trueFlag to show management interface

This is the invite request without the inviter and initiate_login_uri query parameters.

Multi Tenant/Role Apps

If your application supports multiple tenants, and/or you want to enable a user to invite other users to have a specific role, then you need to provide the context of the invitation.

If your application supports multiple roles, but you only allow invited users to have one role, then you don't need this feature.

For example, the Hellō Developer Console is a multi tenant, multi role application. A user may belong to one or more Publishers (Teams), and may have either the Admin or Tester role in a given publisher. When a user wants to invite other users to be members of the team, the publisher identifier (tenant) and the role (admin or tester) are included in the query:

Let's step through what happens when an admin (Jane) for a Publisher of Hellō Applications (Jane's Team) invites another admin (Jack) to be a member of their team in the Hellō Developer Console (Console).

Invite Request

a. Jane is logged into the Console, and clicks the invite button in the admin section of member tab.

b. Jane is redirected to (unescaped and line breaks added for readability):

https://wallet.hello.coop/invite
?client_id=hello_console
&initiate_login_uri=https://console.hello.coop
&events_uri=https://admin.hello.coop/hello/events
&return_uri=https://console.hello.coop
&inviter=265a56a3-ac04-471c-832e-5e16a74eb1f1
&tenant=d09a69db-828e-4411-b1df-386f9524ee4f
&app_name=Jane's+Team
&role=admin
&prompt=Jane+invited+you+to+be+an+admin+for+Jane's+Team

c. Jane enters Jack's email (jack@example.com) and sends the invitation.

Invite Acceptance

a. Jack receives the email invitation, clicks the accept, logs into Hellō, and chooses which information to release to the Hellō Developer Console, and then clicks the Continue button.

b. Hellō sends a signed JWT to the Console's events_uri (webhook). Here is the payload:

{
  "iss":"https://issuer.hello.coop",
  "aud":"hello_console",
  "https://hello.coop/invite/accepted":{
    "inviter":"265a56a3-ac04-471c-832e-5e16a74eb1f1",
    "tenant":"d09a69db-828e-4411-b1df-386f9524ee4f",
    "role":"admin",
    "invitee": {
      "sub":"755f8bab-d839-4b03-ae3e-078aece7d965",
      "email":"jack@example.com"
    }
  }
}

Event Verification

The Console then:

a. Verifies the JWT and signature signed by Hellō.

b. Confirms that Jane is an admin for Jane's Team - IE checks that Jane is authorized to make the invitation.

c. Adds Jack as an admin to Jane's Team

d. Replies with a 202 response to Hellō

Invitee Login

a. Hellō then redirects Jack to the Console.

b. The Console processes the authorization response as usual, and Jack is now an Admin in Jane's Team.

Query Parameters

The events_uri is required if any of role, tenant, or state are provided.

NameDescription
roleAn identifier string passed back to the app in the event JWT as the role property.
tenantAn identifier string passed back to the app in the event JWT as the tenant property.
stateAn identifier string passed back to the app in the event JWT as the state property.
Can be used for arbitrary state information.
events_uriThe webhook where event JWTs are posted after the user consents to login to the application, but before being redirected to the application.
The hostname of the events_uri must match the hostname used in the initiate_login_uri and return_uri.

Event JWT Properties

See example above for additional context

NameDescription
isshttps://issuer.hello.coop The Hellō Issuer
audYour application's client_id
https://hello.coop/invite/acceptedThe event object
   inviterYour app's sub of the inviter.
   roleThe role query parameter if provided when creating invite
   tenantThe tenant query parameter if provided when creating invite
   stateThe state query parameter if provided when creating invite
   inviteeThe invitee object
       subThe sub of the invitee
       emailThe verified email address of the invitee