Authentication

​

Authentication Overview

• user — User accounts (id, email, role, orgId)
• session — Active sessions
• account — OAuth/provider accounts (Microsoft SSO)
• verification — Email/phone verifications

​

Sign-In Methods

​

Email / Password

POST https://auth-dev.openinsure.dev/api/auth/sign-in/email
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "••••••••"
}

{
  "user": { "id": "usr_…", "email": "user@example.com", "role": "org_admin" },
  "session": { "id": "ses_…", "expiresAt": "2026-03-08T14:00:00Z" },
  "token": "eyJhbGciOiJIUzI1NiJ9…"
}

​

Microsoft SSO (mhcis.com Tenant)

1. Redirect the user to the auth worker:
   Copy

   GET https://auth-dev.openinsure.dev/api/auth/sign-in/microsoft?callbackURL=<portal_url>/api/auth/callback
   
2. Auth worker redirects to Azure AD for user authentication.
3. Azure AD redirects back to /api/auth/callback/microsoft on the auth worker.
4. Auth worker issues a signed JWT and redirects to <portal_url>/api/auth/callback?token=<JWT>.
5. Each portal’s /api/auth/callback route reads ?token=JWT, sets the portal-specific cookie, and redirects to the dashboard.

​

Session Management

​

JWT Format

{
  "sub": "usr_01J8K3M4N5P6Q7R8S9T0",
  "org": "org_01HW3K2T9Z6D4V8X5N1M",
  "role": "org_admin",
  "iat": 1741430400,
  "exp": 1741459200
}

​

Portal JWT Cookies

1. Reads the ?token=JWT query parameter.
2. Verifies the JWT against JWT_SECRET.
3. Sets the portal-specific cookie.
4. Redirects to the dashboard.

​

Policyholder OTP Login (Mobile + Portal)

# Step 1: Request OTP (sends 6-digit code to email on file)
POST /auth/policyholder-otp-request
Content-Type: application/json

{ "policyNumber": "MHC-COM-2026-04821" }

# Step 2: Verify OTP and receive JWT
POST /auth/policyholder-token
Content-Type: application/json

{ "policyNumber": "MHC-COM-2026-04821", "otp": "123456" }

{
  "token": "eyJhbGciOiJIUzI1NiJ9…",
  "role": "policyholder",
  "orgId": "org_uuid",
  "sub": "policy-id",
  "policyNumber": "MHC-COM-2026-04821",
  "insuredName": "Midwest Freight Corp"
}

• OTP is stored in KV with 10-minute TTL and cleared after use
• JWT includes sub (policy ID), org, role, policyNumber, insuredName
• The mobile app stores the JWT in SecureStore (Keychain) and adds biometric re-auth
• The web portal sets it as the oi_session cookie

​

Using the React Auth Hook

import { AuthProvider, useAuth } from '@openinsure/auth-hooks';

function App() {
  return (
    <AuthProvider baseURL="/api/auth">
      
    </AuthProvider>
  );
}

function Dashboard() {
  const { user, token, loading, login, logout } = useAuth();

  if (loading) return <div>Loading...</div>;
  if (!user) return <div>Please log in</div>;

  return (
    <div>
      <p>Welcome, {user.email}</p>
      <button onClick={logout}>Logout</button>
    </div>
  );
}

​

API Keys

​

Key Types

​

Example Request

curl -X GET https://api.openinsure.dev/v1/policies \
  -H "Authorization: Bearer oik_live_abc123..."

​

Roles & Permissions

​

Relationship-Based Access Control (ReBAC)

• “Can this Producer view a Claim linked to their Policy?”
• “Can this Underwriter approve a submission above their authority limit?”

​

Multi-Tenancy

1. JWT Claims — Every token contains an org claim
2. App-Level Tenant Isolation — All queries are scoped by orgId in application middleware, ensuring queries only return rows matching the user’s organization
3. Application Middleware — All API routes validate org scope before processing

// Example: orgId scoping applied by middleware before every query
const policies = await db.select().from(policiesTable).where(eq(policiesTable.orgId, ctx.orgId));

​

Environment Variables