Callback handler

The callback handler is a redirect you implement in your app to allow users to sign in to the UserHub Portal. You must first have authentication working in your app (e.g. Auth0, Firebase Auth, custom setup, etc) before proceeding.

At a high level, this is what the flow would look like for a user attempting to visit the portal:

userhub portal login flow
userhub portal login flow

Setup Access to Admin API

Follow the Admin API Getting Started guide to set up the required credentials to make requests to the Admin API.

Add a Callback Endpoint

Add a path to your app that authenticates the user or sends them through your sign-in or sign-up flow if required.

You'll need to keep track of the full callback path and redirect the user to it after signing them in.

Here is a basic example of what that might look like:

def userhub_callback():
    user_id = session.get("user_id")
    if not user_id:
        return redirect(url_for('app.signin', redirect_url=request.url))

Note that the user_id above should be the identifier used by your identity provider that you track throughout your app, not a UserHub-generated user id.

Create Portal Session

Next, you need to generate a redirect URL by calling the Create Portal session endpoint. The redirect URL will be supplied in the response, which you can use to send your user directly to the Portal.

Here is a more complete example:

@app.route("/userhub", methods=["GET"])
def userhub_callback():
    user_id = session.get("user_id")
    if not user_id:
        return redirect(url_for('app.signin', redirect_url=request.url))

    api_url = ""
    api_key = os.environ["USERHUB_ADMIN_API_KEY"]
    connection_id = os.environ["USERHUB_USERS_PROVIDER_CONNECTION_ID"]
    portal_url = request.args.get("portalUrl")

    res =
        headers={"Authorization": f"Bearer {api_key}"},
        json={"portalUrl": portal_url},
    res_data = response.json()

    return redirect(res_data["redirectUrl"])

The user_id variable in the above should be the identifier used by the User Provider (e.g. google-oauth2|1030...). The connection_id variable should be your User Provider connection identifier (e.g. conn_2A4rzn...). When you use the {user_id}@{connection_id} format, UserHub will attempt to automatically import the user if it doesn't already exist in UserHub.

The portalUrl is a query parameter included in the initial UserHub Portal response that allows more granular control over the exact Portal URL you would like your user to end up (e.g. /billing or /members). It must be included in the body of the createPortalSession request, so that the user can be redirected there after being signed in.

The response will include a redirectUrl, which will include a token that signs the user in and redirects them to the portalUrl. Your callback handler should redirect the user to this URL.

Register Your Callback URL

The final step is to enable the UserHub Portal and register your callback URL.

  1. Go to the Admin Console and click [Portal][/docs/portal] under Tenant settings
  2. Enter your newly created Callback URL (e.g. following the examples above, if your app runs at and your callback route is defined as /userhub, you would enter
  3. Click Save

You should now see the Portal URL link at the top of the settings page. Click it to try signing in to the Portal.


Turn users intorevenue

Subscribe to monthly product updates

© 2024 UserHub


    UserHub & Auth0UserHub & Stripe BillingUserHub & Google CloudUserHub & FirebaseUserHub & Custom Auth