Multi-Tenant User Onboarding and Invitation Guide

This guide details how client applications (e.g., your connected SaaS products) can invite and onboard users to organizations using Fabrixly IDS.

Onboarding Models

You can onboard users using one of two patterns:

1. Zero-Managed Onboarding (Fabrixly IDS sends the email)
2. App-Managed Onboarding (Your SaaS sends custom email invite links)

Pattern 1: Zero-Managed Onboarding

In this flow, you call the Fabrixly IDS API, and Fabrixly IDS takes care of sending the onboarding email.

sequenceDiagram
    participant Admin as SaaS Admin
    participant App as SaaS Backend
    participant Zero as Fabrixly IDS API
    participant User as Alice (Email)

    Admin->>App: Invites Alice (alice@example.com) to Org B
    App->>Zero: POST /api/users (alice@example.com)
    Note over Zero: Links Alice to Org B.<br/>If new: generates password.
    Zero-->>User: Sends Onboarding Welcome Email
    User->>Zero: Clicks Get Started, logs in

1. API Call from your SaaS Backend

• Method: POST
• URL: https://ids.fabrixly.com/api/users
• Headers: Authorization: Bearer <M2M_Token_or_Admin_Token>

Request Body:

{
  "email": "alice@example.com",
  "firstName": "Alice",
  "lastName": "Smith",
  "organizationId": "org-uuid-here",
  "roleNames": ["MEMBER"],
  "teamIds": []
}

2. User Experience

• Fabrixly IDS sends a professional welcome email containing a login link: https://ids.fabrixly.com/login
• Existing Users: Log in with their current password and are automatically placed in the context of the new organization.
• New Users: Log in with the password configured by the admin (or reset it) and start using the app.

Pattern 2: App-Managed Onboarding (Custom Invite Link)

In this flow, your SaaS application sends a customized email with an invitation link that resolves through your application.

Sequence Flow

sequenceDiagram
    participant User as Alice (Browser)
    participant App as SaaS App
    participant Zero as Fabrixly IDS
    
    User->>App: Clicks invite link (accept-invite?org_id=org_123&email=alice@example.com)
    App->>User: 302 Redirect to Fabrixly IDS (oidc/auth with login_hint=alice@example.com)
    User->>Zero: Authenticates / Registers
    Zero->>User: 302 Redirect to SaaS Callback (callback?code=code_xyz)
    User->>App: Passes auth code
    App->>Zero: POST oidc/token (Exchange code)
    Zero-->>App: Returns access & ID tokens
    App->>Zero: POST /api/users (onboard/link user to org_123)
    App->>User: Redirects to SaaS workspace

Step-by-Step Implementation

Step 1: Send your custom Invite Email

Your SaaS app sends an email containing a link back to your app:

https://my-saas-app.com/accept-invite?org_id=org_123&email=alice@example.com

Step 2: Handle the Invite Route & Redirect to Fabrixly IDS

When the user hits your endpoint, save the org_id in cookies or local storage, and redirect the browser to the Fabrixly IDS authorization endpoint.

Express.js Example:

app.get('/accept-invite', (req, res) => {
    const { org_id, email } = req.query;

    // Save target organization context to session/cookies
    res.cookie('pending_invite_org', org_id, { httpOnly: true });

    // Build authorization redirect
    const zeroIdsAuthUrl = `https://ids.fabrixly.com/oidc/auth` +
        `?client_id=saas_client_abc` +
        `&redirect_uri=https://my-saas-app.com/callback` +
        `&response_type=code` +
        `&scope=openid email profile` +
        `&login_hint=${encodeURIComponent(email)}`;

    res.redirect(zeroIdsAuthUrl);
});

Step 3: Fabrixly IDS Authenticates the User

Alice registers or logs in on the Fabrixly IDS OIDC login screen.

Step 4: Handle Callback & Exchange Code

Once Alice is authenticated, Fabrixly IDS redirects to your callback page. Exchange the code for tokens:

• Endpoint: POST https://ids.fabrixly.com/oidc/token

Payload:

{
  "client_id": "saas_client_abc",
  "client_secret": "saas_client_secret_xyz",
  "grant_type": "authorization_code",
  "code": "auth_code_12345",
  "redirect_uri": "https://my-saas-app.com/callback"
}

Step 5: Onboard the User to the Organization in Fabrixly IDS

In your callback handler, retrieve the pending org_id from step 2, and call the Fabrixly IDS management API to link the user to the organization:

• Method: POST
• URL: https://ids.fabrixly.com/api/users
• Headers: Authorization: Bearer <M2M_Token_or_Admin_Token>
• Note: Since Alice already authenticated in step 3, Fabrixly IDS links her account to org_123 and skips password creation. She enters the SaaS workspace immediately.

Request Body:

{
  "email": "alice@example.com",
  "organizationId": "org_123", // target organization
  "roleNames": ["MEMBER"],
  "teamIds": []
}