Callback handler

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 this might look like:

@app.route("/userhub")
def userhub_callback():
    user_id = session.get("user_id")
    if not user_id:
        # This should sign the user-in/sign-up and redirect back to the
        # "/userhub?portalUrl=..." on success.
        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))

    admin_api = AdminApi(os.environ["ADMIN_API_KEY"])
    
    # This is the connection ID for your user connection/provider
    # (e.g. Auth0, Custom Users, etc...).
    connection_id = os.environ["USER_PROVIDER_CONNECTION_ID"]

    res = admin_api.users.create_portal_session(
        user_id=f"{user_id}@{connection_id}",
        portal_url=request.args.get("portalUrl"),
    )

    return redirect(res.redirect_url)

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. 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 under Tenant settings
2. Enter your newly created Callback URL (e.g. following the examples above, if your app runs at example.com and your callback route is defined as /userhub, you would enter https://example.com/userhub)
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.