> ## Content Index
> Fetch the complete content index at: https://blog.fabrixly.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# Multi-Tenant User Onboarding and Invitation Guide
- URL: https://blog.fabrixly.com/multi-tenant-user-onboarding-3/
- Published: 2026-07-07T14:10:32.000Z
- Updated: 2026-07-07T14:38:14.000Z
- Author: Fabrixly
- Tags: Documentation, Multi-Tenant, Fabrixly-IDS

# 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.

```mermaid
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**:

```json
{
  "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

```mermaid
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:**

```javascript
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**:

```json
{
  "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**:

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

```