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:

1. 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)
2. Navigate to Stripe Dashboard
3. Click the account switcher in the upper left corner and click New account
4. Enter an account name and click Create account
5. 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:

1. Open the UserHub Admin Console and navigate to the Billing tab in Connections
2. Click Stripe
3. Select Test mode and click Connect
4. You'll be redirected to the Stripe connect page
5. Select the account you just created
6. 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:

1. Open the UserHub Admin Console and navigate to the Products section
2. Click the New Product button
3. Enter Pro plan for the Display name
4. Enter pro-plan for the Unique ID
5. Click the Create button

Next, you'll create an individual plan:

1. Navigate to the Plans section
2. Click the New Plan button
3. Enter Pro for the Display name
4. Select User for the Account type
5. Click the Next button
6. Select Pro plan for the plan product
7. Click the Continue to pricing button
8. Click Add monthly price, click Set price, enter 10 for the Price, and click Save
9. Click Add yearly price, click Set price, enter 100 for the Price, and click Save
10. Click Save and Publish

Finally, you should configure the feature list and set the plan to publicly visible:

1. Click the Settings tab
2. Enter For professional users for the Description
3. Enter 7 for Trial days
4. Toggle the Public visibility to enabled
5. Enter Everything in free, plus: for Title under Features
6. Click Add new feature and enter Unlimited workspaces
7. Click Add new feature again and enter Phone support
8. Click Save changes

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

Listen for Account Changes#

Now that the Portal is setup 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 or seats 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