IAM Multi-Tenancy

Browser / API client
        │
        │  Authorization: Bearer <JWT>
        ▼
┌─────────────────────┐
│   API Gateway       │  ← JWT validation via JWKS
│   (KrakenD)         │  ← Claims → X-IAM-* headers
└──────────┬──────────┘
           │  X-IAM-User-Id: <sub>
           │  X-IAM-Org: <owner>
           │  X-IAM-Roles: <roles>
           ▼
┌──────────────────────────────────────┐
│  ATS  │  BD  │  TA  │  Commerce ... │
│  (all services trust X-IAM-* headers │
│   or validate JWT directly)          │
└──────────────────────────────────────┘
           │
           ▼
   Liquid IAM (id.liquidity.io)
   ├── OAuth2 / OIDC
   ├── SAML / LDAP
   ├── WebAuthn / Passkeys
   ├── 40+ social providers
   ├── RBAC via Casbin
   └── SCIM provisioning

Liquid IAM
├── org: liquidity          ← Liquidity.io (primary)
│   ├── users (investors, traders)
│   ├── roles (investor, trader, admin, operator)
│   └── clients (exchange-frontend, mobile-app, api-keys)
├── org: vcc                ← VCC white-label tenant
│   ├── users
│   ├── roles
│   └── clients
└── org: mlc                ← MLC white-label tenant
    ├── users
    ├── roles
    └── clients

const response = await fetch('https://iam.liquidity.io/api/login/oauth/access_token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: process.env.IAM_CLIENT_ID,
    client_secret: process.env.IAM_CLIENT_SECRET,
    scope: 'trading market_data reporting',
  }),
});

const { access_token, expires_in } = await response.json();
// access_token is a JWT signed by IAM RSA key
// expires_in is typically 7200 (2 hours)

import { BrowserIamSdk } from '@hanzo/iam';

const iam = new BrowserIamSdk({
  serverUrl: 'https://iam.liquidity.io',
  clientId: 'exchange-frontend',
  redirectUri: window.location.origin + '/callback',
});

// Redirect to IAM login page
await iam.signIn('code');

// After redirect back, exchange code for tokens
const tokens = await iam.handleCallback();
// tokens.accessToken, tokens.refreshToken, tokens.idToken

// Registration
await iam.webauthn.register();

// Authentication
const tokens = await iam.webauthn.authenticate();

{
  "iss": "https://iam.liquidity.io",
  "sub": "usr_a1b2c3d4e5f6",
  "owner": "org_liquidity",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "roles": ["trader", "investor"],
  "scope": "trading market_data",
  "iat": 1711100000,
  "exp": 1711107200
}

GET https://iam.liquidity.io/.well-known/jwks

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "iam-rsa-2026-03",
      "use": "sig",
      "alg": "RS256",
      "n": "...",
      "e": "AQAB"
    }
  ]
}

package auth

import (
    "context"
    "fmt"
    "net/http"

    "github.com/liquidityio/iam/sdk"
)

var iamClient = sdk.NewClient("https://iam.liquidity.io")

func ValidateToken(ctx context.Context, token string) (*sdk.Claims, error) {
    claims, err := iamClient.ValidateToken(ctx, token)
    if err != nil {
        return nil, fmt.Errorf("iam: invalid token: %w", err)
    }
    if claims.Owner == "" {
        return nil, fmt.Errorf("iam: missing organization claim")
    }
    return claims, nil
}

// Middleware extracts organization_id for DB scoping
func OrgMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Behind Gateway: trust X-IAM-Org header
        orgID := r.Header.Get("X-IAM-Org")
        if orgID == "" {
            http.Error(w, "missing organization", http.StatusForbidden)
            return
        }
        ctx := context.WithValue(r.Context(), "organization_id", orgID)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

import { IamClient } from '@hanzo/iam';

const iam = new IamClient({
  serverUrl: 'https://iam.liquidity.io',
});

// Validate JWT and extract claims
const claims = await iam.validateToken(token);
// claims.sub       → user ID
// claims.owner     → organization ID
// claims.roles     → ["trader", "investor"]

// In any service handler
func (h *Handler) CreateOrder(w http.ResponseWriter, r *http.Request) {
    orgID := r.Context().Value("organization_id").(string)
    userID := r.Header.Get("X-IAM-User-Id")
    roles := r.Header.Get("X-IAM-Roles") // comma-separated

    // Casbin enforcement happens at Gateway level
    // By the time the request reaches the service, it is authorized
    // Service only needs to scope data to organization_id

    order, err := h.ats.CreateOrder(r.Context(), orgID, req)
    if err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }
    json.NewEncoder(w).Encode(order)
}

{
  "endpoint": "/v1/orders",
  "method": "POST",
  "backend": [
    {
      "url_pattern": "/v1/orders",
      "host": ["http://ats.backend.svc.cluster.local:8080"]
    }
  ],
  "extra_config": {
    "auth/validator": {
      "alg": "RS256",
      "jwk_url": "https://iam.liquidity.io/.well-known/jwks",
      "propagate_claims": [
        ["sub", "X-IAM-User-Id"],
        ["owner", "X-IAM-Org"],
        ["roles", "X-IAM-Roles"]
      ]
    }
  }
}

import { useIam, useAuth } from '@hanzo/iam/react';

function TradingDashboard() {
  const { user, organization, roles } = useIam();
  const { logout } = useAuth();

  if (!user) return <LoginPage />;

  return (
    <div>
      <h1>{organization.name} Exchange</h1>
      <p>Welcome, {user.name}</p>
      <p>Roles: {roles.join(', ')}</p>
      {roles.includes('admin') && <AdminPanel />}
      <button onClick={logout}>Sign Out</button>
    </div>
  );
}

{
  "keys": [
    { "kid": "iam-rsa-2026-03", "kty": "RSA", "alg": "RS256", "..." : "..." },
    { "kid": "legacy-hmac", "kty": "oct", "alg": "HS256", "..." : "..." }
  ]
}