Skip to main content

Core Concepts

This page explains the core abstractions of Ithbat IAM. Reading it will help you make better integration decisions and understand the reasoning behind the API design.

Tenants​

A tenant is the top-level isolation boundary in Ithbat IAM. Every user, role, group, session, and configuration record belongs to exactly one tenant. Tenants are completely isolated from each other — a user in tenant A cannot be seen, queried, or authenticated against tenant B.

When you sign up for Ithbat IAM, you create at least one tenant. A typical setup has one tenant per environment (development, staging, production). Products that serve multiple independent customers model each customer as a tenant, giving them separate user directories, separate branding, and separate settings.

Every tenant-scoped API request must include the X-Tenant-ID header with the tenant's UUID.

Tenant configuration covers branding (logo, colors, custom domain), security policies (password strength, MFA enforcement, session lifetime, IP allowlists), and feature flags. All of these are managed through the Settings API or the admin dashboard.

Users​

A user is an authenticated identity within a tenant. Users are identified by their email address.

FieldTypeNotes
idUUIDSystem-generated, immutable
tenantIdUUIDThe owning tenant
emailstringUnique within a tenant
firstNamestringOptional profile field
familyNamestringOptional profile field
phoneNumberstringOptional
isActivebooleanWhether the account is active
mfaEnabledbooleanWhether any MFA factor is enrolled
emailVerifiedbooleanWhether the email address has been verified
createdAtstringISO 8601
updatedAtstringISO 8601

Users go through a lifecycle: active is the normal state, suspended means an admin has disabled access without deleting the account. Suspended users cannot log in and have all active sessions revoked. Accounts locked after too many failed login attempts can be unlocked via POST /api/v1/users/{id}/unlock.

Email verification is required by default. After registration, the user receives a verification link. You can resend it via POST /api/v1/auth/resend-verification.

Authentication​

Ithbat IAM supports multiple authentication methods:

Email and password is the baseline method. Passwords are validated against your tenant's password policy (minimum length, complexity, history).

Passwordless uses time-limited magic links sent to the user's email. Call POST /api/v1/auth/passwordless/start with the email address, then POST /api/v1/auth/passwordless/verify with the token from the link.

Social login delegates authentication to a federated provider. Redirect the user to GET /api/v1/auth/social/{provider}/login and handle the callback at GET /api/v1/auth/social/{provider}/callback. Supported providers are configured per-tenant in the IdP settings.

SAML 2.0 enables enterprise single sign-on where your tenant acts as the Service Provider and an enterprise IdP (Active Directory, Okta, Azure AD, etc.) acts as the Identity Provider. SAML flows are available at /api/v1/auth/saml/{tenant_id}/.

All successful authentications return accessToken, refreshToken, expiresIn, and user fields. When MFA is required, accessToken and refreshToken are absent and the response contains mfaRequired: true and mfaToken instead. See the Authentication API for the complete flow.

Multi-Factor Authentication (MFA)​

Ithbat IAM supports multiple second-factor methods:

TOTP (authenticator app) — Set up via POST /api/v1/auth/mfa/setup which returns a QR code URI. Confirm setup by calling POST /api/v1/auth/mfa/verify-setup with a valid code. During login, complete MFA with POST /api/v1/auth/mfa/verify.

Backup codes — Generated at TOTP setup. Each code can only be used once. Regenerate them via POST /api/v1/auth/mfa/backup-codes. Use them at login via POST /api/v1/auth/mfa/verify-backup.

SMS OTP — Available as a feature-gated option. Set up via POST /api/v1/auth/mfa/sms/setup.

WebAuthn (passkeys, hardware keys) — Register a credential via POST /api/v1/mfa/webauthn/register/start and /finish. Authenticate via POST /api/v1/mfa/webauthn/login/start and /finish. List and delete credentials via /api/v1/mfa/webauthn/credentials.

Roles and Permissions​

Ithbat IAM uses role-based access control (RBAC) with a flat permission model. Permissions follow the resource:action convention.

Roles are named collections of permissions. You create roles via POST /api/v1/roles and assign them to users via POST /api/v1/users/{id}/roles. A user can have multiple roles; their effective permissions are the union of all permissions across all assigned roles.

Groups are collections of users. Assign roles to groups to apply permissions to all members at once. When a role is assigned to a group, every member inherits that role's permissions. This is the recommended way to manage permissions at scale.

curl -X POST https://api.ithbat.io/api/v1/users/{id}/roles \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{"roleId": "role-uuid-here"}'

The available system permissions can be listed via GET /api/v1/permissions.

Sessions​

A session represents a user's authenticated context on a device or in a browser. Ithbat IAM supports concurrent sessions — the same user can be logged in from multiple devices simultaneously, each with an independent refresh token.

Sessions are created at login and destroyed at logout. You can:

  • List all active sessions for the current user: GET /api/v1/auth/sessions
  • Revoke a specific session: DELETE /api/v1/auth/sessions/{id}
  • Revoke all other sessions (keep current): DELETE /api/v1/auth/sessions

Administrators can view sessions for a specific user via GET /api/v1/users/{id}/sessions and forcibly terminate them via DELETE /api/v1/users/{id}/sessions.

Tokens​

Ithbat IAM issues two types of tokens on every successful authentication:

Access token — a short-lived JWT (default: 1 hour) that authorizes requests to protected endpoints. It contains the user's ID, tenant ID, roles, and permissions as claims. Pass it in the Authorization: Bearer header. Validate it against the OIDC public keys published at GET /.well-known/openid-configuration.

Refresh token — a long-lived token used to obtain new access tokens. Subject to rotation: each call to POST /api/v1/auth/refresh invalidates the previous refresh token and issues a new one. Store refresh tokens securely (HttpOnly cookies for browsers, secure storage for mobile apps).

OAuth2 and OIDC​

Ithbat IAM acts as an OpenID Connect (OIDC) Identity Provider. Your applications can delegate authentication to Ithbat using the standard Authorization Code flow.

Discovery endpoint: GET /.well-known/openid-configuration — returns the OIDC configuration including JWKS URI, supported scopes, and endpoint URLs.

Authorization endpoint: GET /oauth/authorize — initiate the authorization code flow.

Token endpoint: POST /oauth/token — exchange an authorization code for tokens, or use client credentials grant.

Note: The /oauth/authorize and /oauth/token endpoints are on the root path (no /api/v1 prefix).

OAuth clients are managed via the admin API at /api/v1/oauth/admin/clients. Each client defines its allowed redirect URIs, grant types, and scopes.

Audit​

All significant actions in Ithbat IAM are recorded as audit events. Each event captures:

  • Who performed the action (actor ID, actor email)
  • What happened (event type, e.g., user.suspended)
  • What was affected (resource type and ID)
  • When and from where (timestamp, IP address)

Administrators can query audit events via GET /api/v1/audit/events and login history via GET /api/v1/audit/logins. Individual users can query their own activity via GET /api/v1/audit/me/activity and GET /api/v1/audit/me/logins.

Organizations​

Organizations model the B2B use case where your tenant's users represent multiple independent companies or departments. Each organization has its own member list and role assignments.

A user can belong to multiple organizations simultaneously, each with a different role. Create organizations via POST /api/v1/organizations, add members via POST /api/v1/organizations/{id}/members, and set per-organization roles via PUT /api/v1/organizations/{id}/members/{userId}/roles.

Regions and Data Residency​

Ithbat IAM operates across multiple regions. When you create a tenant, you select its region. All data — users, audit logs, sessions, and tokens — is stored and processed within that region.

Available regions can be listed via GET /api/v1/regions. Tenant registration is done via POST /api/v1/tenants/register.