User Management

Ithbat IAM provides a complete user lifecycle API and admin console. Users can be created manually, imported in bulk via CSV, provisioned automatically via SCIM, or created through self-registration and SAML JIT provisioning.

User profile fields

Every user account contains the following standard fields:

Field	Type	Description
`id`	UUID	Unique identifier
`email`	string	Primary email, must be unique within the tenant
`firstName`	string	Given name
`lastName`	string	Family name
`phone`	string	Phone number (optional)
`locale`	string	BCP 47 language tag, e.g. `en`, `ar`
`status`	enum	`active`, `suspended`, `pending`
`emailVerified`	bool	Whether the email address has been verified
`externalId`	string	ID from an external system (e.g. IdP user ID)
`metadata`	object	Arbitrary key-value pairs for your own use
`createdAt`	timestamp	Account creation time
`lastLoginAt`	timestamp	Most recent successful login

Inviting users

The recommended way to add users is by invitation. Ithbat sends an email with a secure link. The user clicks the link, sets their password, and their account is activated.

Via admin console

Go to Users → Invite User.
Enter the email address and optionally a first and last name.
Select the roles to assign on acceptance.
Click Send Invitation.

Via API

POST /api/v1/invitations
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "email": "[email protected]",
  "firstName": "Jane",
  "lastName": "Doe",
  "roleIds": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"]
}

Response:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "email": "[email protected]",
  "status": "pending",
  "expiresAt": "2026-03-03T10:00:00Z",
  "createdAt": "2026-02-24T10:00:00Z"
}

Invitations expire after 7 days. Resend an expired invitation:

POST /api/v1/invitations/{id}/resend
Authorization: Bearer {token}

Bulk invitations

Send up to 50 invitations in a single request:

POST /api/v1/invitations/bulk
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "invitations": [
    { "email": "[email protected]", "firstName": "User", "lastName": "One" },
    { "email": "[email protected]", "firstName": "User", "lastName": "Two" }
  ],
  "roleIds": ["7c9e6679-..."]
}

Creating users directly

Create users without the invitation email flow. The user will be created in active status with emailVerified: false unless overridden.

POST /api/v1/users
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "email": "[email protected]",
  "firstName": "Jane",
  "lastName": "Doe",
  "phone": "+966501234567",
  "locale": "ar"
}

Response:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "tenantId": "c2e3f4a5-...",
  "email": "[email protected]",
  "firstName": "Jane",
  "lastName": "Doe",
  "phone": "+966501234567",
  "locale": "ar",
  "status": "active",
  "emailVerified": false,
  "createdAt": "2026-02-24T10:00:00Z",
  "updatedAt": "2026-02-24T10:00:00Z"
}

Viewing users

List all users

GET /api/v1/users
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}

Supports pagination (page, limit) and filtering by status, email, and more.

Get a single user

GET /api/v1/users/{id}
Authorization: Bearer {token}

Get the current authenticated user

GET /api/v1/users/me
Authorization: Bearer {user_token}

Updating users

Update profile fields

PUT /api/v1/users/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phone": "+966501234567",
  "locale": "en"
}

Update metadata

Attach arbitrary key-value metadata to a user without touching the standard profile fields:

PATCH /api/v1/users/{id}/metadata
Authorization: Bearer {token}
Content-Type: application/json

{
  "department": "Engineering",
  "employeeId": "EMP-1042",
  "costCenter": "CC-500"
}

Suspending and reactivating users

Suspension prevents sign-in while preserving the user's data, sessions, and role assignments. All active sessions are invalidated immediately on suspension.

Suspend a user

POST /api/v1/users/{id}/suspend
Authorization: Bearer {token}

Reactivate a suspended user

POST /api/v1/users/{id}/reactivate
Authorization: Bearer {token}

Unlock a locked account

Accounts are locked automatically after repeated failed login attempts (configured by your password policy). Unlock manually:

POST /api/v1/users/{id}/unlock
Authorization: Bearer {token}

Deleting users

Deletion is permanent and irreversible. All sessions, role assignments, group memberships, and personal data are removed.

DELETE /api/v1/users/{id}
Authorization: Bearer {token}

Bulk delete

DELETE /api/v1/users/bulk
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "userIds": [
    "3fa85f64-...",
    "7c9e6679-..."
  ]
}

Bulk import via CSV

Import large numbers of users from a CSV file.

Prepare the CSV

The CSV must include a header row. Supported columns:

email,firstName,lastName,phone,locale,externalId
[email protected],Jane,Doe,+966501234567,en,EMP-1042
[email protected],John,Smith,,ar,EMP-1043

Required: email. All other columns are optional.

Import via API

POST /api/v1/users/import
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: multipart/form-data

[email protected]

The import is processed asynchronously. The response includes a job ID:

{
  "jobId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "status": "queued"
}

Poll for job status:

GET /api/v1/jobs/{jobId}/status
Authorization: Bearer {token}

Export users to CSV

POST /api/v1/users/export
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "format": "csv",
  "fields": ["email", "firstName", "lastName", "status", "createdAt"]
}

Returns a job ID. Retrieve the result when complete:

GET /api/v1/jobs/{jobId}/result
Authorization: Bearer {token}

Password policies

Configure password requirements for your tenant.

Get the current policy

GET /api/v1/tenant/password-policy
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}

Response:

{
  "minLength": 8,
  "requireUppercase": true,
  "requireLowercase": true,
  "requireNumbers": true,
  "requireSymbols": false,
  "maxAge": 90,
  "preventReuse": 5,
  "maxLoginAttempts": 5,
  "lockoutDuration": 900
}

Update the policy

PUT /api/v1/tenant/password-policy
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "minLength": 12,
  "requireUppercase": true,
  "requireLowercase": true,
  "requireNumbers": true,
  "requireSymbols": true,
  "maxAge": 90,
  "preventReuse": 10,
  "maxLoginAttempts": 5,
  "lockoutDuration": 1800
}

Field	Description
`minLength`	Minimum password length (1–128)
`requireUppercase`	At least one uppercase letter required
`requireLowercase`	At least one lowercase letter required
`requireNumbers`	At least one digit required
`requireSymbols`	At least one special character required
`maxAge`	Password expiry in days (0 = never expires)
`preventReuse`	Number of previous passwords that cannot be reused
`maxLoginAttempts`	Failed attempts before account lockout
`lockoutDuration`	Lockout duration in seconds

Session management

View a user's active sessions

GET /api/v1/users/{id}/sessions
Authorization: Bearer {token}

Revoke all sessions for a user

DELETE /api/v1/users/{id}/sessions
Authorization: Bearer {token}

User API reference summary

Method	Endpoint	Permission
`GET`	`/api/v1/users`	`user:read`
`GET`	`/api/v1/users/{id}`	`user:read`
`POST`	`/api/v1/users`	`user:write`
`PUT`	`/api/v1/users/{id}`	`user:write`
`DELETE`	`/api/v1/users/{id}`	`user:delete`
`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`	`/api/v1/users/import`	`user:write`
`POST`	`/api/v1/users/export`	`user:write`
`PATCH`	`/api/v1/users/{id}/metadata`	`user:write`
`POST`	`/api/v1/invitations`	`invitation:write`
`POST`	`/api/v1/invitations/bulk`	`invitation:write`
`POST`	`/api/v1/invitations/{id}/resend`	`invitation:write`
`POST`	`/api/v1/invitations/{id}/revoke`	`invitation:write`

Next steps

RBAC & Permissions — assign roles to users
SCIM 2.0 — automate user provisioning from your IdP
Directory Sync — sync users from Active Directory or LDAP
Audit Logs — view user creation, suspension, and deletion events

User profile fields​

Inviting users​

Via admin console​

Via API​

Bulk invitations​

Creating users directly​

Viewing users​

List all users​

Get a single user​

Get the current authenticated user​

Updating users​

Update profile fields​

Update metadata​

Suspending and reactivating users​

Suspend a user​

Reactivate a suspended user​

Unlock a locked account​

Deleting users​

Bulk delete​

Bulk import via CSV​

Prepare the CSV​

Import via API​

Export users to CSV​

Password policies​

Get the current policy​

Update the policy​

Session management​

View a user's active sessions​

Revoke all sessions for a user​

User API reference summary​

Next steps​

User profile fields

Inviting users

Via admin console

Via API

Bulk invitations

Creating users directly

Viewing users

List all users

Get a single user

Get the current authenticated user

Updating users

Update profile fields

Update metadata

Suspending and reactivating users

Suspend a user

Reactivate a suspended user

Unlock a locked account

Deleting users

Bulk delete

Bulk import via CSV

Prepare the CSV

Import via API

Export users to CSV

Password policies

Get the current policy

Update the policy

Session management

View a user's active sessions

Revoke all sessions for a user

User API reference summary

Next steps