Skip to main content

Register and Login with Userdocks SDKs

This is the standard and recommended way to integrate register and login with Userdocks.

Use one of the official SDKs:

With this setup, your users register and sign in on the Userdocks-hosted pages, and your app receives the authenticated user back on your redirect URL.

If you do not want to use the hosted Userdocks register and login pages, follow the advanced guide instead: Advanced Register, Login, and Tenants.

Before You Start​

  • First follow Connect Your App in Userdocks.
  • Keep your app UUID ready. In SDK examples this is usually used as clientId.
  • Make sure the redirect URL in your app matches the redirect URL configured in the Userdocks dashboard.

Flow Overview​

The recommended flow looks like this:

  1. Your app initializes the Userdocks SDK.
  2. The user clicks sign up or sign in in your app.
  3. The SDK redirects the user to the Userdocks-hosted auth page.
  4. The user registers or signs in on the Userdocks page.
  5. Userdocks redirects the user back to your app with an authorization code.
  6. Your app exchanges that code for tokens through the SDK.
  7. Your app loads the signed-in user and tenant data from the API.

Important behavior: when a user signs up through the hosted Userdocks flow, registration still automatically creates the user's initial tenant and makes the registering user an admin of that tenant.

Step 1: Choose Your SDK​

Use the SDK that matches your app:

The standard auth flow is the same with both SDKs. The main difference is how you initialize the SDK inside your app.

Step 2: Configure The SDK​

Both SDKs need the same app and auth-server configuration.

Typical options object:

const options = {
  authServer: {
    domain: process.env.NEXT_PUBLIC_AUTH_SERVER_DOMAIN!,
    apiUri: process.env.NEXT_PUBLIC_AUTH_SERVER_API_URL!,
    loginUri: process.env.NEXT_PUBLIC_AUTH_SERVER_LOGIN_URL!,
    sdkUri: process.env.NEXT_PUBLIC_AUTH_SERVER_SDK_URL!,
    paths: {
      refresh: process.env.NEXT_PUBLIC_AUTH_SERVER_PATH_REFRESH!,
      exchangeCodeForToken:
        process.env.NEXT_PUBLIC_AUTH_SERVER_PATH_EXCHANGE_CODE_FOR_TOKEN!,
    },
  },
  app: {
    refreshType: process.env.NEXT_PUBLIC_APP_REFRESH_TYPE! as 'refresh',
    origin: process.env.NEXT_PUBLIC_APP_ORIGIN!,
    clientId: process.env.NEXT_PUBLIC_USERDOCKS_CLIENT_ID!,
    redirectUri: process.env.NEXT_PUBLIC_APP_REDIRECT_URI!,
  },
};

The important values are:

  • clientId: your Userdocks app UUID
  • redirectUri: the callback URL you configured in the Userdocks dashboard
  • loginUri: the Userdocks-hosted login and register application

Step 3: Redirect Users To The Hosted Userdocks Pages​

Web Client SDK​

import userdocks from '@userdocks/web-client-sdk';

await userdocks.initialize(options);

await userdocks.redirectTo({
  type: 'signUp',
});

await userdocks.redirectTo({
  type: 'signIn',
});

React SDK​

import { useEffect, useState } from 'react';
import { UserdocksProvider, useUserdocks } from '@userdocks/react-sdk';

function AuthButtons() {
  const [isLoading, setIsLoading] = useState(true);
  const { userdocks } = useUserdocks();

  useEffect(() => {
    (async () => {
      if (!userdocks.isInitialized()) {
        await userdocks.initialize();
      }

      setIsLoading(false);
    })();
  }, [userdocks]);

  if (isLoading) {
    return <div>Loading...</div>;
  }

  return (
    <>
      <button onClick={() => userdocks.redirectTo({ type: 'signUp' })}>
        Sign Up
      </button>
      <button onClick={() => userdocks.redirectTo({ type: 'signIn' })}>
        Sign In
      </button>
    </>
  );
}

export default function App() {
  return (
    <UserdocksProvider options={options}>
      <AuthButtons />
    </UserdocksProvider>
  );
}

At this point, Userdocks handles the hosted registration and login screens for you.

Step 4: Handle The Callback In Your App​

After a successful sign-up or sign-in, Userdocks redirects the user back to your redirectUri with a code, state, and client ID in the URL.

On that callback page, exchange the code for tokens.

Web Client SDK​

import userdocks from '@userdocks/web-client-sdk';

await userdocks.initialize(options);

const isSuccessfulExchange = await userdocks.exchangeCodeForToken();

React SDK​

import { useEffect } from 'react';
import { useUserdocks } from '@userdocks/react-sdk';

export default function CallbackPage() {
  const { userdocks } = useUserdocks();

  useEffect(() => {
    (async () => {
      if (!userdocks.isInitialized()) {
        await userdocks.initialize();
      }

      await userdocks.exchangeCodeForToken();
    })();
  }, [userdocks]);

  return <div>Signing you in...</div>;
}

After the code exchange succeeds, the user is authenticated in your app.

Step 5: Load The User And Tenant​

Once the SDK has exchanged the code for tokens, load the current user from:

Use the tenant relationship in that response to load the tenant:

For newly registered users, the initial tenant usually comes from tenantsAsAdmin[0].tenant.

Step 6: Continue Onboarding​

After sign-up or sign-in, many apps continue with these authenticated actions:

Continue to Mollie Payments if your signed-in user needs to save cards, make one-time payments, or start subscriptions.

When To Use The Advanced Flow Instead​

Use the advanced flow only if you want to build your own registration and login forms instead of using the hosted Userdocks pages.

That guide documents the direct public API flow: Advanced Register, Login, and Tenants.