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

# Administrator and User Journey Guide
- URL: https://blog.fabrixly.com/user-journey-guide/
- Published: 2026-07-07T03:08:36.000Z
- Updated: 2026-07-07T06:30:56.000Z
- Author: Fabrixly
- Tags: Documentation, Guide, Fabrixly-IDS

# User Journey Guide

This document outlines the complete journey for Administrators and End-Users interacting with the Identity Server. It covers organization onboarding, user management, and the Single Sign-On (SSO) experience.

---

## Part 1: Administrator Journey

### Prerequisites

- **System Admin Token**: Management API requests require a standard JWT Bearer token (`Authorization: Bearer <admin-jwt-token>`) obtained by calling the login endpoint.
- **Base URL**: `https://ids.fabrixly.com`

### Step 1: Onboarding an Organization

**Actor**: System Administrator **Goal**: Create a new tenant (Organization) in the system.

1. **Obtain System Admin JWT**:
  - *Outcome*: Copy the `token` from the response JSON and use it as `<admin-jwt-token>`.
2. **Create Organization**:
  - **Endpoint**: `POST /api/organizations`
  - **Headers**: `Authorization: Bearer <admin-jwt-token>`
  - **Outcome**: Returns the created Organization object, including its `id` (e.g., `org-uuid`).

**cURL**:

```bash
curl -X POST https://ids.fabrixly.com/api/organizations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-jwt-token>" \
  -d '{"name": "Acme Corp", "domain": "acme.com"}'

```

**Payload**:

```json
{
  "name": "Acme Corp",
  "domain": "acme.com"
}

```

*Action*: Log in using System Administrator credentials.

```bash
curl -X POST https://ids.fabrixly.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@example.com", "password": "your-admin-password"}'

```

### Step 2: Onboarding an Organization Administrator

**Actor**: System Administrator **Goal**: Create the first administrator for the new organization.

1. **Create Org Admin User**:
  - **Endpoint**: `POST /api/users`
  - **Headers**: `Authorization: Bearer <admin-jwt-token>` (System Admin can create users anywhere)
  - **Outcome**: Returns the created User object, including `id` (e.g., `org-admin-uuid`).

**cURL**:

```bash
curl -X POST https://ids.fabrixly.com/api/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-jwt-token>" \
  -d '{
    "email": "admin@acme.com",
    "password": "securePassword123",
    "firstName": "Alice",
    "lastName": "Admin",
    "organizationId": "org-uuid",
    "roleNames": ["ORG_ADMIN"]
  }'

```

**Payload**:

```json
{
  "email": "admin@acme.com",
  "password": "securePassword123",
  "firstName": "Alice",
  "lastName": "Admin",
  "organizationId": "org-uuid",
  "roleNames": ["ORG_ADMIN"]
}

```

### Step 3: Setting up Roles and Teams

**Actor**: Organization Administrator (`org-admin-uuid`) **Goal**: Define structure for the organization.

1. **Create a Team**:
  - **Endpoint**: `POST /api/teams`
2. **Create a Role** (if custom roles are needed beyond ORG\_ADMIN/MEMBER):
  - **Endpoint**: `POST /api/roles`

**cURL**:

```bash
curl -X POST https://ids.fabrixly.com/api/roles \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-jwt-token>" \
  -d '{"name": "DEVELOPER", "organizationId": "org-uuid"}'

```

**cURL**:

```bash
curl -X POST https://ids.fabrixly.com/api/teams \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-jwt-token>" \
  -d '{"name": "Engineering", "organizationId": "org-uuid"}'

```

### Step 4: Onboarding End-Users

**Actor**: Organization Administrator **Goal**: Add regular employees to the organization.

1. **Create User**:
  - **Endpoint**: `POST /api/users`

**cURL**:

```bash
curl -X POST https://ids.fabrixly.com/api/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-jwt-token>" \
  -d '{
    "email": "bob@acme.com",
    "password": "password123",
    "firstName": "Bob",
    "lastName": "Builder",
    "organizationId": "org-uuid",
    "roleNames": ["DEVELOPER"],
    "teamNames": ["Engineering"]
  }'

```

### Step 5: Registering an OIDC Client (Application)

**Actor**: Organization Administrator **Goal**: Connect an application (e.g., "Acme Dashboard") to the Identity Server.

1. **Register Client**:
  - **Endpoint**: `POST /api/clients`
  - **Outcome**: Returns `client_id` and `client_secret`. Save these!

**cURL**:

```bash
curl -X POST https://ids.fabrixly.com/api/clients \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-jwt-token>" \
  -d '{
    "client_name": "Acme Dashboard",
    "redirect_uris": ["https://ids.fabrixly.com/callback"],
    "requires_consent": false
  }'

```

**Payload**:

```json
{
  "client_name": "Acme Dashboard",
  "redirect_uris": ["https://ids.fabrixly.com/callback"],
  "requires_consent": false
}

```

---

## Part 2: End-User Journey (SSO Flow)

### Scenario: Logging into "Acme Dashboard"

**Actor**: Bob (`bob@acme.com`) **Goal**: Access the dashboard using his Acme Corp credentials.

### Step 1: Initiate Login

1. **User Action**: Bob visits the Acme Dashboard (e.g., `https://ids.fabrixly.com`).
2. **User Action**: Clicks the **"Login with SSO"** button.
3. **System Action**: The Dashboard redirects Bob's browser to the Identity Server's authorization endpoint.
  - *URL*: `https://ids.fabrixly.com/auth?client_id=...&response_type=code&scope=openid...`

### Step 2: Authentication (Login Page)

1. **Navigation**: Bob is now on the Identity Server's **Login Page** (`https://ids.fabrixly.com/interaction/.../login`).
2. **User Action**: Bob enters his email (`bob@acme.com`) and password (`password123`).
3. **User Action**: Clicks **"Sign In"**.
  - *Alternative*: If he doesn't have an account and registration is enabled, he could click "Create an account" here.

### Step 3: Consent (Optional)

- *Note*: If the client was registered with `requires_consent: false` (as done in Step 5 above), this step is **skipped**.
1. **Navigation**: If consent is required, Bob sees the **Consent Page**.
  - "Acme Dashboard wants to access your profile."
2. **User Action**: Bob clicks **"Allow"**.

### Step 4: Redirect & Token Exchange

1. **System Action**: The Identity Server redirects Bob back to the Dashboard's `redirect_uri` (`https://ids.fabrixly.com/callback`) with an authorization `code`.
2. **System Action**: The Dashboard backend automatically exchanges this `code` for an **Access Token** and **ID Token** by calling the Identity Server's `/token` endpoint.
3. **System Action**: The Dashboard verifies the ID Token.

### Step 5: Access Granted

1. **Navigation**: Bob is redirected to the Dashboard's **Home/Profile Page**.
2. **Outcome**: Bob sees "Welcome, Bob!" and his profile details (fetched from the Identity Server).
3. **Session**: Bob is now logged in. If he visits another app using the same Identity Server, he won't need to enter his password again (SSO).