Quick Start

This guide takes you from zero to a working authenticated API call. By the end you will have registered a user, logged them in, and made an authenticated request using the returned JWT.

Prerequisites

• An Ithbat IAM account — sign up at ithbat.io
• curl or any HTTP client (Postman, Insomnia, etc.)
• Node.js 18+ if you want to use the TypeScript SDK

---

Step 1: Create your account and tenant

Go to ithbat.io and sign up. During onboarding you will create your first tenant — an isolated identity namespace for your application. Give it a name (e.g., "My App - Development") and select your preferred data region.

Once created, the dashboard shows your Tenant ID — a UUID that looks like 3f8a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c. Keep this handy; you will pass it in every API request as the X-Tenant-ID header.

---

Step 2: Get your API credentials

For end-user authentication flows (registration, login), you only need your Tenant ID — these endpoints are public but tenant-scoped.

For admin operations (user management, role management, etc.) you need a valid access token obtained by logging in as an admin user.

tip

Store your tenant ID and credentials in environment variables and never commit them to source control.

---

Step 3: Install the SDK (optional)

If you prefer working with a typed client rather than raw HTTP, install the TypeScript SDK:

npm install @ithbatiam/sdk

You can follow along with either cURL or SDK examples throughout this guide.

---

Step 4: Register your first user

The registration endpoint creates a new user in your tenant. The X-Tenant-ID header is required.

Request fields:

• email — required
• firstName — optional
• familyName — optional
• password — optional (if omitted, an invite-style flow applies)

curl -X POST https://api.ithbat.io/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -d '{
    "email": "[email protected]",
    "firstName": "Jane",
    "familyName": "Doe",
    "password": "SecurePass123!"
  }'

SDK equivalent:

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

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

const result = await ithbat.auth.register({
  email: '[email protected]',
  firstName: 'Jane',
  familyName: 'Doe',
  password: 'SecurePass123!',
  tenantId: process.env.ITHBAT_TENANT_ID,
});

note

Ithbat IAM sends a verification email after registration. In development you can configure your tenant's email verification settings in the dashboard, or create users via the admin API.

---

Step 5: Authenticate the user

Once registered, log the user in to receive JWT tokens.

curl -X POST https://api.ithbat.io/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123!"
  }'

Response (200 OK) — success:

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "user": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email": "[email protected]",
    "firstName": "Jane",
    "familyName": "Doe"
  }
}

Response (200 OK) — MFA required:

{
  "mfaRequired": true,
  "mfaToken": "mfa_eyJhbGciOiJIUzI1NiJ9..."
}

When mfaRequired is true, accessToken and refreshToken are absent. Pass the mfaToken to POST /api/v1/auth/mfa/verify with the user's TOTP code to complete login.

SDK equivalent:

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

if (result.mfaRequired) {
  const mfaResult = await ithbat.auth.verifyMfa({
    mfaToken: result.mfaToken,
    code: '123456',
  });
  ithbat.setAccessToken(mfaResult.accessToken);
} else {
  ithbat.setAccessToken(result.accessToken);
}

---

Step 6: Make an authenticated request

Use the accessToken from the login response to call protected endpoints.

curl https://api.ithbat.io/api/v1/users/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"

SDK equivalent:

const me = await ithbat.auth.me();
console.log(me.email);

---

Step 7: List users (admin)

List users in the tenant. Requires the user:read permission.

curl "https://api.ithbat.io/api/v1/users?page=1&limit=25" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"

SDK equivalent:

const result = await ithbat.users.listUsers({ page: 1, limit: 25 });
console.log(result.items);       // User[]
console.log(result.totalItems);  // total count

listUsers() returns a PagedResult<User> with .items and .totalItems.

---

Step 8: Refresh the access token

Access tokens expire after expiresIn seconds (default 3600). Use the refresh token to obtain a new one.

curl -X POST https://api.ithbat.io/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

warning

Ithbat IAM uses refresh token rotation. Each refresh call issues a new refresh token and invalidates the previous one. Always store the latest refresh token.

---

Step 9: Log out

Invalidate the current session:

curl -X POST https://api.ithbat.io/api/v1/auth/logout \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

---

Next steps

Topic	Link
Understand tenants, tokens, and RBAC	Core Concepts
Full REST API reference	API Overview
Authentication endpoints	Authentication API
User management	Users API
Admin endpoints	Admin API