OutOfScope IAM SDK

TypeScript/JavaScript client for the OutOfScope Platform IAM service. The SDK wraps the HTTP API with typed helpers for authentication, session management, and admin user management.

Installation

npm install @outofscope/sdk-iam

The package targets modern runtimes with fetch available. For Node.js 18 or earlier, provide your own fetch implementation (e.g., node-fetch or undici).

Creating a client

import { createIamClient } from "@outofscope/sdk-iam";

const iam = createIamClient({
  baseUrl: "https://api.outofscope.example.com",
  appKey: "my-app-key", // optional
  getSessionId: () => localStorage.getItem("IAM_SESSION") ?? undefined, // optional
  getTenantId: () => localStorage.getItem("IAM_TENANT") ?? undefined, // optional
  // fetchImpl: customFetch, // optional, defaults to global fetch
});

Configuration options:

• baseUrl (required): Base URL of the OutOfScope API Gateway.
• appKey (optional): App identifier sent as x-app-key for all endpoints.
• getSessionId (optional): Function that returns the current session ID. When provided, requests automatically include x-session-id unless explicitly overridden per call.
• getTenantId (optional): Function that returns the active tenant. When provided, requests automatically include x-tenant-id unless explicitly overridden per call.
• fetchImpl (optional): Custom fetch to use in browsers, Node, or tests.

Example browser-friendly setup that mirrors the usage shown above:

import { createIamClient } from "@outofscope/sdk-iam";
import { loadActiveTenantId } from "./tenantStorage.js";

const SESSION_KEY = "iamSessionId";

const loadStoredSessionId = () =>
  typeof window === "undefined" ? "" : window.localStorage.getItem(SESSION_KEY) || "";

export const iamClient = createIamClient({
  baseUrl: window.location.origin,
  appKey: window.IAM_APP_KEY,
  getSessionId: loadStoredSessionId,
  getTenantId: loadActiveTenantId,
});

Authentication

The SDK sends headers automatically when values are available:

• x-session-id is attached from the per-call options, the request body (where supported), or getSessionId() when configured.
• x-tenant-id is attached from the per-call options or getTenantId() when configured.
• x-app-key is automatically attached to every request when appKey is configured.

const session = await iam.login({
  email: "[email protected]",
  password: "P@ssw0rd",
});

// later, when the user wants to sign out
await iam.logout({ sessionId: session.sessionId });

Change a password by passing the active session via the helper or directly in the request body:

await iam.changePassword(
  { oldPassword: "old", newPassword: "new" },
  { sessionId: session.sessionId }
);

To resolve the current session user:

const me = await iam.me({ sessionId: session.sessionId });
console.log(me.user.displayName);

Admin operations

All admin helpers accept an optional { sessionId } object for authenticated calls and automatically attach x-app-key when appKey is configured.

// Create a user and membership
const createResponse = await iam.createUser(
  {
    email: "[email protected]",
    displayName: "New User",
    password: "StrongPass123!",
    tenantId: "tenant-1",
    roleKey: "admin",
  },
  { sessionId: session.sessionId }
);

// Update profile
await iam.updateUser(
  createResponse.user.id,
  { displayName: "Updated User", isActive: true },
  { sessionId: session.sessionId }
);

// Manage memberships
await iam.addMembership(
  createResponse.user.id,
  { tenantId: "tenant-2", roleKey: "member" },
  { sessionId: session.sessionId }
);
await iam.updateMembership(
  createResponse.user.id,
  "membership-id",
  { roleKey: "viewer" },
  { sessionId: session.sessionId }
);

List users with filters:

const users = await iam.listUsers(
  { email: "[email protected]", tenantId: "tenant-1", roleKey: "admin" },
  { sessionId: session.sessionId }
);

Fetch permission and role catalogs:

const permissions = await iam.listPermissions({ sessionId: session.sessionId });
const roles = await iam.listRoles({ sessionId: session.sessionId });

Responses and errors

• Successful calls return typed objects, e.g., { ok: true, sessionId, user } for login.
• Error responses include a code such as INVALID_REQUEST, INVALID_SESSION, or WEAK_PASSWORD. Failed requests reject with Error("Request failed: <code or status text>"), making the code available in error.message.
• Session handling is explicit via { sessionId } options or implicit via getSessionId(); if omitted, the server may rely on cookies when available.

Testing

Run the unit tests with Vitest:

npm test

Publishing notes

Build artifacts are generated with npm run build, producing dist/index.js and dist/index.d.ts suitable for npm publishing.