Skip to main content

Advanced Register, Login, and Tenants

This guide documents the advanced end-user flow for teams that want to build their own register and login UI instead of using the hosted Userdocks pages.

For most integrations, this is not the recommended starting point.

The standard way to use Userdocks is:

If you want Userdocks to handle the hosted sign-up and sign-in pages for you, follow the recommended guide first: Register and Login with Userdocks SDKs.

Before You Start​

  • First follow Connect Your App in Userdocks.
  • Keep your app UUID ready.
  • Make sure your app knows the same redirect URL that is configured in the Userdocks dashboard.
  • Decide that you really want a custom register and login UI in your own app.

Flow Overview​

The advanced custom flow looks like this:

  1. Register a user with POST /api/v1/users.
  2. Confirm the user email with PUT /api/v1/user-confirm-hashes/:hash.
  3. Start login with POST /api/v1/codes.
  4. Exchange the code for tokens with POST /api/v1/tokens.
  5. Load the signed-in user with GET /api/v1/users/me.
  6. Load the tenant from the user response with GET /api/v1/tenants/:tenantUuid.

Important behavior: registration automatically creates the user and an initial tenant, and the registering user becomes an admin of that tenant.

Step 1: Register The User​

Call POST /api/v1/users to create the user.

Typical request:

{
  "email": "user@example.com",
  "password": "VeryStrongPass123!",
  "passwordConfirmation": "VeryStrongPass123!",
  "acceptedTermsAndConditions": true,
  "acceptedDataPrivacy": true,
  "acceptPrivacyPolicy": false,
  "appUuid": "11111111-1111-1111-1111-111111111111"
}

Typical query parameters:

  • type=confirmation
  • language=en

What this does:

  • creates the user
  • creates the initial tenant automatically
  • associates the new user as an admin of that tenant
  • sends the confirmation email

Step 2: Confirm The User Email​

Before the user can sign in, the email must be verified.

Use the confirmation hash from the email with PUT /api/v1/user-confirm-hashes/:hash.

After this step, the user is ready for the login flow.

Step 3: Start Login With A Code​

Call POST /api/v1/codes with the user email, password, app UUID, state, and redirect URL.

Typical request:

{
  "appUuid": "11111111-1111-1111-1111-111111111111",
  "email": "user@example.com",
  "password": "VeryStrongPass123!",
  "state": "state-from-client",
  "redirectUri": "https://app.example.com/callback",
  "acceptPrivacyPolicy": false
}

This returns a code redirect URL. Your app then exchanges that authorization code for tokens.

Step 4: Exchange The Code For Tokens​

Call POST /api/v1/tokens with:

  • client_id = your app UUID
  • grant_type = authorization_code
  • the code, state, and redirect_uri from the previous step

The response includes the bearer access token your app will use for signed-in Userdocks requests.

Step 5: Load The Signed-In User​

Call GET /api/v1/users/me with the bearer token.

This response gives you the user profile plus tenant relationships:

  • tenantsAsAdmin
  • tenantsAsUser

For a newly registered user, the first tenant usually comes from tenantsAsAdmin[0].tenant.

Step 6: Load The Tenant​

Take the tenant UUID from the signed-in user response and call GET /api/v1/tenants/:tenantUuid.

This is the tenant your new user can manage immediately after registration.

Because the initial tenant is auto-created during signup, you will usually want to update its display name and address data once the user reaches your app.

Step 7: Update The User And Tenant​

Use these authenticated endpoints to finish onboarding:

This is the point where many apps replace the initial auto-created tenant name with the real company or workspace name the user entered in the onboarding UI.

What To Do Next​

  • Continue to Mollie Payments if your signed-in user needs to save cards or pay from a tenant.
  • Keep using GET /api/v1/users/me as your source of truth for the current user and their available tenant memberships.