@drmhse/sso-sdk 0.3.10 → 0.3.12

package/README.md

@@ -52,6 +52,71 @@ const orgs = await sso.organizations.list();
 console.log(orgs);
 ```
 
+## Understanding Context Modes
+
+AuthOS supports **two initialization modes** that determine how authentication is handled:
+
+### Platform-Level Mode
+
+For platform owners and administrators managing AuthOS itself:
+
+```typescript
+const sso = new SsoClient({
+  baseURL: 'https://sso.example.com'
+});
+
+// Platform-level login (email/password only)
+await sso.auth.login({
+  email: 'admin@platform.com',
+  password: 'SecurePass123!'
+});
+// JWT contains: { is_platform_owner: true, ... }
+```
+
+**When to use:** Admin dashboards, platform management tools, internal tooling.
+
+### Multi-Tenant Mode
+
+For end-user applications that integrate with AuthOS:
+
+```typescript
+// Initialize with org and service context
+const sso = new SsoClient({
+  baseURL: 'https://sso.example.com'
+});
+
+// OAuth redirects require org + service to determine:
+// 1. Which tenant's OAuth credentials (BYOO) to use
+// 2. Which service the identity is attributed to
+const loginUrl = sso.auth.getLoginUrl('github', {
+  org: 'acme-corp',      // Organization slug
+  service: 'main-app',   // Service within that org
+  redirect_uri: 'https://app.acme.com/callback'
+});
+
+// Password login can also include org context
+await sso.auth.login({
+  email: 'user@example.com',
+  password: 'SecurePass123!',
+  org_slug: 'acme-corp'  // Optional: scopes JWT to this org
+});
+// JWT contains: { org: 'acme-corp', ... }
+```
+
+**When to use:** Customer-facing apps, SaaS products, multi-tenant applications.
+
+### Why Context Matters
+
+| Context | JWT Claims | OAuth Credentials Used |
+|---------|-----------|----------------------|
+| Platform-level | `is_platform_owner: true` | Platform's `PLATFORM_*` credentials |
+| Multi-tenant | `org: 'slug'`, `service: 'slug'` | Tenant's BYOO credentials (or platform fallback) |
+
+The `org` and `service` parameters ensure:
+- **Identity isolation**: User identities are scoped to specific services
+- **Credential isolation**: Each tenant can use their own OAuth app credentials
+- **Proper attribution**: Login events are tracked per organization/service
+
 **New to the SDK?** Start with the **[Getting Started Guide →](https://drmhse.com/docs/sso/sdk/getting-started)** for a step-by-step tutorial showing how to authenticate users from scratch, handle token refresh, and implement logout.
 
 **Essential Guides:**
@@ -91,19 +156,23 @@ if (accessToken) {
 ### Password Authentication
 
 ```typescript
-// Register new user
+// Register new user (tenant-first: always include org + service for proper attribution)
 await sso.auth.register({
   email: 'user@example.com',
   password: 'SecurePass123!',
-  org_slug: 'acme-corp'
+  org_slug: 'acme-corp',     // Your organization
+  service_slug: 'main-app'   // Your application
 });
+// User identity is now scoped to your org and service
 
-// Login with password - session automatically saved
+// Login with password (service-scoped: include org + service)
 await sso.auth.login({
   email: 'user@example.com',
-  password: 'SecurePass123!'
+  password: 'SecurePass123!',
+  org_slug: 'acme-corp',     // Your organization
+  service_slug: 'main-app'   // Your application
 });
-// Tokens are now automatically stored and injected on all requests
+// JWT is now scoped to org + service
 
 // Enable MFA
 const mfaSetup = await sso.user.mfa.setup();

package/dist/index.d.mts

@@ -309,7 +309,17 @@ interface RefreshTokenResponse {
 interface RegisterRequest {
     email: string;
     password: string;
+    /**
+     * Organization slug for tenant context.
+     * When provided, the user is attributed to this organization.
+     */
     org_slug?: string;
+    /**
+     * Service slug for service attribution.
+     * When provided with org_slug, creates a scoped identity.
+     * This ensures password users are tracked the same as OAuth users.
+     */
+    service_slug?: string;
 }
 /**
  * Registration response
@@ -323,6 +333,17 @@ interface RegisterResponse {
 interface LoginRequest {
     email: string;
     password: string;
+    /**
+     * Organization slug for context.
+     * When provided, scopes the session to this organization.
+     */
+    org_slug?: string;
+    /**
+     * Service slug for service-scoped access.
+     * When provided with org_slug, limits access to this specific service.
+     * Only required for regular members; org owners/admins can omit.
+     */
+    service_slug?: string;
 }
 /**
  * Forgot password request payload

package/dist/index.d.ts

@@ -309,7 +309,17 @@ interface RefreshTokenResponse {
 interface RegisterRequest {
     email: string;
     password: string;
+    /**
+     * Organization slug for tenant context.
+     * When provided, the user is attributed to this organization.
+     */
     org_slug?: string;
+    /**
+     * Service slug for service attribution.
+     * When provided with org_slug, creates a scoped identity.
+     * This ensures password users are tracked the same as OAuth users.
+     */
+    service_slug?: string;
 }
 /**
  * Registration response
@@ -323,6 +333,17 @@ interface RegisterResponse {
 interface LoginRequest {
     email: string;
     password: string;
+    /**
+     * Organization slug for context.
+     * When provided, scopes the session to this organization.
+     */
+    org_slug?: string;
+    /**
+     * Service slug for service-scoped access.
+     * When provided with org_slug, limits access to this specific service.
+     * Only required for regular members; org owners/admins can omit.
+     */
+    service_slug?: string;
 }
 /**
  * Forgot password request payload

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drmhse/sso-sdk",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "description": "Zero-dependency TypeScript SDK for AuthOS, the multi-tenant authentication platform",
   "main": "dist/index.js",
   "module": "dist/index.mjs",