API Reference

The Ithbat IAM REST API provides programmatic access to all platform capabilities — user management, authentication flows, RBAC, groups, organizations, audit logs, and more.

Base URL

All API requests target the versioned base path:

https://api.ithbat.io/api/v1/

Regional endpoints are available for data residency requirements:

Region	Base URL
Global	https://api.ithbat.io/api/v1/
KSA	https://api.sa.ithbat.io/api/v1/
Egypt	https://api.eg.ithbat.io/api/v1/

Use the regional endpoint matching your tenant's data residency setting. The tenant's region is set at creation time and cannot be changed.

OAuth endpoints (/oauth/authorize, /oauth/token) are on the root path with no /api/v1 prefix:

https://api.ithbat.io/oauth/authorize
https://api.ithbat.io/oauth/token

Authentication

All protected endpoints require a Bearer JWT access token in the Authorization header:

Authorization: Bearer <access_token>

Obtain an access token by calling POST /api/v1/auth/login. Tokens expire after 3600 seconds. Use POST /api/v1/auth/refresh with your refresh token to obtain a new access token without re-authenticating.

Tenant Context

Multi-tenant requests must include the tenant identifier:

X-Tenant-ID: <tenant_uuid>

Requests without X-Tenant-ID are scoped to the tenant resolved from the authenticated user's JWT.

Request Format

All request bodies must be JSON with the appropriate content type header:

Content-Type: application/json

Example Authenticated Request

curl -X GET "https://api.ithbat.io/api/v1/users/me" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Error Format

Errors return a structured envelope with a machine-readable code:

{
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Email or password is incorrect"
  }
}

Validation errors include per-field details:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      { "field": "email", "message": "must be a valid email address" },
      { "field": "password", "message": "must be at least 8 characters" }
    ]
  }
}

HTTP Status Codes

Code	Meaning
200	Success
201	Resource created
400	Bad request — malformed JSON or missing required fields
401	Unauthorized — missing or invalid access token
403	Forbidden — authenticated but insufficient permissions
404	Not found — resource does not exist or is not visible to the tenant
409	Conflict — resource already exists (duplicate email, etc.)
429	Too many requests — rate limit exceeded
500	Internal server error

Pagination

List endpoints accept page and limit query parameters:

Parameter	Type	Default	Description
page	integer	1	Page number, 1-indexed
limit	integer	25	Results per page

Example:

curl "https://api.ithbat.io/api/v1/users?page=2&limit=50" \
  -H "Authorization: Bearer <token>" \
  -H "X-Tenant-ID: <tenant_id>"

Rate Limiting

Sensitive endpoints (login, password reset, MFA verification) are rate limited per IP. When the limit is exceeded the API returns HTTP 429.

Versioning

The current API version is v1. The version is part of the URL path: /api/v1/. Breaking changes will be introduced in a new version with a deprecation notice and migration window.

Common Error Codes

Code	Description
INVALID_CREDENTIALS	Email or password is incorrect
ACCOUNT_SUSPENDED	User account has been suspended
ACCOUNT_NOT_VERIFIED	Email address has not been verified
MFA_REQUIRED	MFA verification is required to continue
TOKEN_EXPIRED	Access token has expired
TOKEN_INVALID	Access token is malformed or has been revoked
TENANT_NOT_FOUND	The specified tenant does not exist
TENANT_SUSPENDED	The tenant account has been suspended
PERMISSION_DENIED	The authenticated user lacks the required permission
RESOURCE_NOT_FOUND	The requested resource does not exist
DUPLICATE_EMAIL	A user with this email already exists
VALIDATION_ERROR	One or more request fields failed validation
RATE_LIMIT_EXCEEDED	Too many requests in the current time window
IP_NOT_WHITELISTED	The request IP address is not in the tenant's allowlist

Endpoint Summary

Public (no JWT required)

Method	Path	Description
POST	/api/v1/auth/login	Login with email and password
POST	/api/v1/auth/register	Register a new user
POST	/api/v1/auth/refresh	Refresh access token
POST	/api/v1/auth/verify-email	Verify email address
POST	/api/v1/auth/resend-verification	Resend verification email
POST	/api/v1/auth/password-reset/initiate	Request password reset email
POST	/api/v1/auth/password-reset/validate	Validate reset token
POST	/api/v1/auth/password-reset/complete	Complete password reset
POST	/api/v1/auth/mfa/verify	Verify TOTP during login
POST	/api/v1/auth/mfa/verify-backup	Verify backup code during login
POST	/api/v1/auth/mfa/sms/verify	Verify SMS OTP during login
POST	/api/v1/auth/mfa/sms/resend	Resend SMS OTP during login
POST	/api/v1/mfa/webauthn/login/start	Start WebAuthn login
POST	/api/v1/mfa/webauthn/login/finish	Finish WebAuthn login
POST	/api/v1/auth/passwordless/start	Send magic link
POST	/api/v1/auth/passwordless/verify	Verify magic link token
GET	/api/v1/auth/social/{provider}/login	Initiate social login
GET	/api/v1/auth/social/{provider}/callback	Social login callback
POST	/api/v1/auth/social/exchange	Exchange social code for tokens
GET	/api/v1/auth/social/providers	List enabled social providers
GET	/api/v1/auth/saml/{tenant_id}/metadata	SAML SP metadata
GET	/api/v1/auth/saml/{tenant_id}/login	Initiate SAML login
POST	/api/v1/auth/saml/{tenant_id}/acs	SAML assertion consumer service
GET	/oauth/authorize	OAuth2 authorization endpoint
POST	/oauth/token	OAuth2 token endpoint
GET	/.well-known/openid-configuration	OIDC discovery document
POST	/api/v1/tenants/register	Register a new tenant
GET	/api/v1/regions	List available regions

JWT-protected (self-service)

Method	Path	Description
GET	/api/v1/users/me	Get own profile
PUT	/api/v1/users/me	Update own profile
POST	/api/v1/auth/logout	Logout
POST	/api/v1/auth/change-password	Change own password
GET	/api/v1/auth/sessions	List own sessions
DELETE	/api/v1/auth/sessions/{id}	Revoke a session
DELETE	/api/v1/auth/sessions	Revoke all other sessions
POST	/api/v1/auth/mfa/setup	Start TOTP MFA setup
POST	/api/v1/auth/mfa/verify-setup	Confirm TOTP MFA setup
POST	/api/v1/auth/mfa/disable	Disable TOTP MFA
POST	/api/v1/auth/mfa/backup-codes	Regenerate backup codes
POST	/api/v1/auth/mfa/sms/setup	Start SMS MFA setup
POST	/api/v1/auth/mfa/sms/verify-setup	Confirm SMS MFA setup
POST	/api/v1/auth/mfa/sms/send	Send SMS OTP
POST	/api/v1/auth/mfa/sms/disable	Disable SMS MFA
POST	/api/v1/mfa/webauthn/register/start	Start WebAuthn registration
POST	/api/v1/mfa/webauthn/register/finish	Finish WebAuthn registration
GET	/api/v1/mfa/webauthn/credentials	List WebAuthn credentials
DELETE	/api/v1/mfa/webauthn/credentials/{id}	Delete WebAuthn credential
GET	/api/v1/audit/me/activity	Get own audit activity
GET	/api/v1/audit/me/logins	Get own login history
GET	/api/v1/tenant/features	Get enabled features for current tenant

JWT-protected (admin — requires permissions)

Method	Path	Permission
GET/POST	/api/v1/users	user:read / user:write
GET/PUT/DELETE	/api/v1/users/{id}	user:read / user:write
POST	/api/v1/users/{id}/suspend	user:write
POST	/api/v1/users/{id}/reactivate	user:write
POST	/api/v1/users/{id}/unlock	user:write
POST	/api/v1/users/bulk	user:write
DELETE	/api/v1/users/bulk	user:write
POST/DELETE	/api/v1/users/{id}/roles, /api/v1/users/{id}/roles/{roleId}	role:write
GET	/api/v1/users/{id}/permissions	user:read
GET	/api/v1/users/{id}/sessions	user:read
DELETE	/api/v1/users/{id}/sessions	user:write
GET/POST	/api/v1/roles	role:read / role:write
GET/PUT/DELETE	/api/v1/roles/{id}	role:read / role:write
GET	/api/v1/roles/permissions	role:read
GET/POST	/api/v1/permissions	permission:read / permission:write
GET/PUT/DELETE	/api/v1/permissions/{id}	permission:read / permission:write
GET/POST	/api/v1/groups	group:read / group:write
GET/PUT/DELETE	/api/v1/groups/{id}	group:read / group:write
GET/POST/DELETE	/api/v1/groups/{id}/members, /api/v1/groups/{id}/members/{uid}	group:read / group:write
GET/POST/DELETE	/api/v1/groups/{id}/roles, /api/v1/groups/{id}/roles/{rid}	group:read / group:write
GET/POST	/api/v1/organizations	organization:read / organization:write
GET/PUT/DELETE	/api/v1/organizations/{id}	organization:read / organization:write
GET/POST/DELETE	/api/v1/organizations/{id}/members	organization:read / organization:write
GET/POST	/api/v1/invitations	invitation:read / invitation:write
GET	/api/v1/tenants/current	tenant:read
GET/POST	/api/v1/tenants	tenant:write
GET/PUT/DELETE	/api/v1/tenants/{id}	tenant:write
GET/POST	/api/v1/oauth/admin/clients	oauth:read / oauth:write
GET/PUT/DELETE	/api/v1/oauth/admin/clients/{id}	oauth:read / oauth:write
GET	/api/v1/audit/events	audit:read
GET	/api/v1/audit/events/{id}	audit:read
GET	/api/v1/audit/logins	audit:read
GET	/api/v1/audit/users/{userId}/activity	audit:read
GET	/api/v1/audit/users/{userId}/logins	audit:read
GET	/api/v1/audit/resources/{type}/{id}/history	audit:read
GET	/api/v1/tenant/settings	settings:read
PATCH	/api/v1/tenant/settings/general	settings:write
PATCH	/api/v1/tenant/settings/security	settings:write
PATCH	/api/v1/tenant/settings/branding	settings:write
GET/PUT	/api/v1/tenant/password-policy	settings:read / settings:write
GET/PUT	/api/v1/tenant/security/ip-whitelist	settings:read / settings:write
POST/DELETE	/api/v1/tenant/custom-domain	settings:write
POST	/api/v1/tenant/custom-domain/verify	settings:write