Authentication Methods

The SDK's auth namespace covers every login flow supported by Ithbat IAM. All methods return promises and throw IthbatError on failure.

Register a new user

SDK: sdk.auth.register(params)

REST: POST /api/v1/auth/register with X-Tenant-ID header

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

console.log(result.id);
console.log(result.message);

Parameters:

Name	Type	Required	Description
`email`	`string`	Yes	User's email address. Must be unique within the tenant.
`password`	`string`	Yes	Must satisfy the tenant's password policy.
`tenantId`	`string`	Yes	The tenant to register the user under.
`firstName`	`string`	No	Given name.
`familyName`	`string`	No	Family / last name.

Returns: RegisterResponse

interface RegisterResponse {
  id: string;
  email: string;
  message: string;
}

Log in with email and password

SDK: sdk.auth.login(params)

REST: POST /api/v1/auth/login with X-Tenant-ID header

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

if (session.accessToken) {
  sdk.setAccessToken(session.accessToken);
  console.log(session.user?.id);
}

Parameters:

Name	Type	Required	Description
`email`	`string`	Yes
`password`	`string`	Yes
`rememberMe`	`boolean`	No	Hint to extend session lifetime.

Returns: LoginResponse

interface LoginResponse {
  accessToken?: string;
  refreshToken?: string;
  expiresIn?: number;
  user?: UserInfo;
  mfaRequired?: boolean;
  mfaToken?: string;
}

interface UserInfo {
  id: string;
  email: string;
  emailVerified: boolean;
  firstName?: string;
  familyName?: string;
  roles?: string[];
}

Handling MFA: If the user has MFA enabled, mfaRequired is true and accessToken / refreshToken are absent. Use the mfaToken to complete the MFA challenge:

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

if (session.mfaRequired) {
  const code = await promptUserForMFACode();
  const fullSession = await sdk.auth.verifyMfa({
    mfaToken: session.mfaToken!,
    code,
  });
  sdk.setAccessToken(fullSession.accessToken);
}

SDK: sdk.auth.verifyMfa(params)

REST: POST /api/v1/auth/mfa/verify

Called during the login flow when mfaRequired: true. Pass the mfaToken from the login response along with the TOTP code:

const fullSession = await sdk.auth.verifyMfa({
  mfaToken: 'the_mfa_token_from_login',
  code: '654321',
});

sdk.setAccessToken(fullSession.accessToken);

Returns: VerifyMfaResponse

interface VerifyMfaResponse {
  accessToken: string;
  refreshToken: string;
  expiresIn: number;
  user: UserInfo;
}

Verify with backup code

SDK: sdk.auth.verifyBackupCode(params)

REST: POST /api/v1/auth/mfa/verify-backup

Use when the user cannot access their authenticator app and must use a one-time backup code instead:

const fullSession = await sdk.auth.verifyBackupCode({
  mfaToken: 'the_mfa_token_from_login',
  code: 'BACKUP-CODE-HERE',
});

sdk.setAccessToken(fullSession.accessToken);

Parameters and return type are the same as verifyMfa.

Log out

SDK: sdk.auth.logout()

REST: POST /api/v1/auth/logout (requires Authorization header)

Invalidates the current session on the server.

await sdk.auth.logout();

Refresh the access token

SDK: sdk.auth.refreshToken(params)

REST: POST /api/v1/auth/refresh

Exchanges a refresh token for a new access token:

const tokens = await sdk.auth.refreshToken({
  refreshToken: 'rt_...',
});

sdk.setAccessToken(tokens.accessToken);

Returns: RefreshTokenResponse

interface RefreshTokenResponse {
  accessToken: string;
  refreshToken: string;
  expiresIn: number;
}

Get the current user

SDK: sdk.auth.me()

REST: GET /api/v1/users/me (requires Authorization header)

Returns the profile of the currently authenticated user:

const me = await sdk.auth.me();
console.log(me.id, me.email, me.roles);

Returns: UserInfo

Initiate password reset

SDK: sdk.auth.resetPassword({ email })

REST: POST /api/v1/auth/password-reset/initiate

Sends a password reset link to the user's email address. The response is always successful regardless of whether the email exists, to prevent email enumeration.

await sdk.auth.resetPassword({ email: '[email protected]' });

Change password

SDK: sdk.auth.changePassword(params)

REST: POST /api/v1/auth/change-password (requires authentication)

await sdk.auth.changePassword({
  oldPassword: 'OldPass123!',
  newPassword: 'NewPass456!',
});

Parameters:

Name	Type	Required	Description
`oldPassword`	`string`	Yes	The user's current password.
`newPassword`	`string`	Yes	The desired new password. Must satisfy tenant password policy.

Verify email address

SDK: sdk.auth.verifyEmail(token)

REST: POST /api/v1/auth/verify-email

The verification email contains a token query parameter. Pass it to confirm the email address:

const params = new URLSearchParams(window.location.search);
await sdk.auth.verifyEmail(params.get('token')!);

Resend verification email

SDK: sdk.auth.resendVerification(email)

REST: POST /api/v1/auth/resend-verification

await sdk.auth.resendVerification('[email protected]');

Machine-to-machine (client credentials)

SDK: sdk.auth.clientCredentials(clientId, clientSecret, scope?)

REST: POST /oauth/token (root origin, not versioned path)

For server-to-server integrations where no user is involved, use OAuth 2.0 client credentials. The scope parameter defaults to 'openid':

const tokens = await sdk.auth.clientCredentials(
  process.env.ITHBAT_CLIENT_ID!,
  process.env.ITHBAT_CLIENT_SECRET!,
);

sdk.setAccessToken(tokens.access_token);

Alternatively, use sdk.authenticate() which calls this method and applies the token automatically:

await sdk.authenticate(
  process.env.ITHBAT_CLIENT_ID!,
  process.env.ITHBAT_CLIENT_SECRET!,
);

Returns: ClientCredentialsResponse

interface ClientCredentialsResponse {
  access_token: string;
  token_type: string;
  expires_in: number;
  scope?: string;
}

Multi-factor authentication (MFA)

MFA setup and management is handled by the sdk.mfa namespace. See Admin Methods for the full reference.

Set up TOTP

const setup = await sdk.mfa.setup({
  method: 'totp',
  password: 'CurrentPass123!',
});

console.log(setup.qrCode);   // Render as <img> for the user to scan
console.log(setup.secret);   // Manual entry fallback

Confirm TOTP setup

const result = await sdk.mfa.verifySetup({
  code: '123456',
  method: 'totp',
});

Regenerate backup codes

const { backupCodes } = await sdk.mfa.regenerateBackupCodes({
  password: 'CurrentPass123!',
});

Disable MFA

await sdk.mfa.disable({
  password: 'CurrentPass123!',
});

Register a new user​

Log in with email and password​

Verify MFA at login​

Verify with backup code​

Log out​

Refresh the access token​

Get the current user​

Initiate password reset​

Change password​

Verify email address​

Resend verification email​

Machine-to-machine (client credentials)​

Multi-factor authentication (MFA)​

Set up TOTP​

Confirm TOTP setup​

Regenerate backup codes​

Disable MFA​

Register a new user

Log in with email and password

Verify MFA at login

Verify with backup code

Log out

Refresh the access token

Get the current user

Initiate password reset

Change password

Verify email address

Resend verification email

Machine-to-machine (client credentials)

Multi-factor authentication (MFA)

Set up TOTP

Confirm TOTP setup

Regenerate backup codes

Disable MFA