Skip to main content

TypeScript SDK

The Ithbat IAM TypeScript SDK (@ithbatiam/sdk) is the fastest way to integrate Ithbat IAM into a JavaScript or TypeScript application. It wraps the full REST API in a strongly-typed, promise-based interface so you can focus on your application instead of HTTP plumbing.

What the SDK provides​

Client-side authentication — Register users, handle login flows (email/password, MFA challenge), manage refresh tokens, and handle logout. The IthbatSDK is safe to use in browser and Node.js environments.

Admin operations — Create and manage users, roles, groups, tenants, sessions, and audit logs from a server-side context using a service account token obtained via client credentials.

Full TypeScript types — Every request body, response payload, and error type is fully typed, reflecting the actual production API.

Supported environments​

EnvironmentNotes
Node.js 18+Full support. Uses the native fetch API.
Browser (modern)Full support via native fetch. Tokens are stored in memory by default.

Installation​

npm install @ithbatiam/sdk
# or
yarn add @ithbatiam/sdk
# or
pnpm add @ithbatiam/sdk

See the Installation guide for full setup instructions including TypeScript configuration and environment variable setup.

Quick example​

import { IthbatSDK } from '@ithbatiam/sdk';

const sdk = new IthbatSDK({
  basePath: 'https://api.ithbat.io/api/v1',
  tenantId: process.env.ITHBAT_TENANT_ID,
});

const session = await sdk.auth.login({
  email: '[email protected]',
  password: 'SecurePass123!',
});

if (session.accessToken) {
  sdk.setAccessToken(session.accessToken);
  const me = await sdk.auth.me();
  console.log(`Hello, ${me.firstName}`);
}

After calling sdk.auth.login() and passing the returned access token to sdk.setAccessToken(), all subsequent SDK calls include the Authorization header automatically.

SDK surface area​

NamespacePurpose
sdk.authLogin, register, logout, password reset, token refresh, current user
sdk.mfaMFA setup, verification, backup codes, SMS
sdk.usersUser management (list, create, update, delete, suspend, role assignment)
sdk.rolesRole and permission management
sdk.groupsGroup management and membership
sdk.tenantsTenant management
sdk.sessionsSession listing and revocation
sdk.auditAudit event queries and login history

Instance methods​

MethodDescription
setAccessToken(token)Set the bearer token used for subsequent requests.
setTenantId(id)Set or change the tenant ID sent as X-Tenant-ID.
authenticate(clientId, clientSecret, scope?)Obtain an access token via client credentials and apply it automatically.
isTokenExpired()Returns true if the current access token is expired or within 60 seconds of expiry.
isAuthError(error)Returns true if the error is a 401 response from the API.
isValidationError(error)Returns true if the error is a 400 validation failure with field details.
getValidationErrors(error)Returns the array of field-level validation errors from a validation error.
destroy()Cleans up the SDK instance.

Resources​