Getting Started

Create Tenant

The first step in getting started with UserHub is to create a tenant.

For this guide, we recommend creating a development mode tenant under your individual account, which will give you a low-risk place to get acquainted with UserHub and experiment.

Connect User Provider

Once you've created your tenant, you must connect your User Provider (identity provider).

UserHub currently supports Auth0, Firebase Auth, Identity Platform, and the ability to implement a custom user provider.

Click one of the links above for instructions to set up your User Provider, and return to this guide when done.

Setup Portal

After you've connected the user provider, you must enable the UserHub Portal from the Portal settings section of the Admin Console.

See the callback handler page for detailed instructions on implementing this redirect and enabling the Portal. Return to this guide when done.

Connect Billing Provider

Next, you must connect Stripe to your tenant. UserHub uses the Stripe Connect platform to create a secure connection between UserHub and Stripe.

For this guide, we recommend you create a dedicated Stripe account:

Sign up for a Stripe account if you don't already have one (you don't need to do any of the activation steps, you only need a test account)
Navigate to Stripe Dashboard
Click the account switcher in the upper left corner and click New account
Enter an account name and click Create account
You only need Test mode for this guide, so you can safely ignore the activation and other onboarding messaging.

Next, connect Stripe to your tenant:

Open the UserHub Admin Console and navigate to Connections via Developers dropdown or Tenant settings
Click Setup for Stripe
Select Test mode and click Connect
You'll be redirected to the Stripe connect page
Select the account you just created
Click Skip this form at the top of the page

Your Stripe account should now be connected to your tenant.

Create Plan

In order to allow users to sign up for a subscription in the Portal you'll need to create a plan.

The first step is to create a product for your plan:

Open the UserHub Admin Console and navigate to the Products section
Click the New Product button
Enter Pro for the Display name
Enter pro for the Unique ID
Click the Create button

Next, you'll create an individual plan:

Navigate to the Plans section
Click the New plan button
Enter Pro for the Display name
Select User for the Account type
Click the Next button
Click the Add your first product link
Select Plan for the product type
Select Pro for the product
Click the Add plan prices button
Click Set price for the Monthly price, enter 10 for the Price, and click Save
Click Set price for the Yearly price, enter 100 for the Price, and click Save
Click Finalize and mark default
Toggle the Show in portal switch

You should now be able to subscribe to the plan from the UserHub Portal.

Listen for Account Changes

Now that the Portal is set up and users can subscribe to plans, you should set up your app to handle events from UserHub.

The two most important events to handle are:

organizations.changed: is triggered when an organization changes, including when an organization is created, updated, or deleted. It is also triggered when the subscription associated with the organization state changes (trialing, active, past due, canceled, etc...) or when the subscription plan changes.
users.changed: is triggered when a user changes, including when a user is created, updated, or deleted. It is also triggered when a user's individual subscription changes or when the user's memberships change.

Follow the instructions in the Webhooks Getting Started guide to start handling events. You should also set up your app with the ability to make requests to the Admin API.

How you handle these events will depend on how your user and organization data is modeled in your database, but we'll list some best practices and hints below:

Get latest data: the webhook payload is always a snapshot of the objects at the time the event was created. We recommend always getting the latest version from the Admin API before updating your database.
Make your handlers idempotent: you should make your webhook handlers idempotent. After getting the latest data from the API, compare it against what's in your database. Merge data as needed and lazily create missing dependencies.
Get subscription state from the account object: the organization and user objects will include the subscription property if they have an active subscription. Use its presence to update the state of the account in your database.
Use product unique IDs to map entitlements: you can save the product unique ID (e.g. pro-plan) to your database and use it to determine which features the account is entitled to use.

members.changed specific handling:

Handle membership changes: the member event will be triggered whenever a user is added to an organization, removed from an organization, or when their role changes. Compare the member object to the state of your database and update as needed.
Handle seat changes: similar to account-level subscription changes, the member event will also be triggered when a subscription associated with a user's membership changes or when the seat assigned to the member changes.

Important organization properties:

organization.subscription: present when the organization has an active subscription
organization.subscription.state: the current state of the organization subscription (trialing, active, past due, etc...)
organization.subscription.plan.product.uniqueId: a developer-defined identifier which can be used to map organization-level entitlements

Important user properties:

user.subscription: present when the user has an active individual subscription
user.subscription.state: the current state of the individual subscription (trialing, active, past due, etc...)
user.subscription.plan.product.uniqueId: a developer-defined identifier which can be used to map user-level entitlements
user.memberships: list of user's memberships
user.memberships[*].role: the user's role within the organization (e.g. owner, admin, etc...)
user.memberships[*].seat: present when the user has a seat assigned in the organization
user.memberships[*].seat.product.uniqueId: developer-defined identifier which can be used to map seat-level entitlements
user.memberships[*].organization.subscription: present when the organization has an active subscription