Users API

User endpoints cover two categories:

Self-service (/users/me) — Any authenticated user managing their own profile and sessions.
Admin user management (/users, /users/{id}) — Requires user:read or user:write permission.

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

GET /api/v1/users/me

Authentication required.

Retrieve the authenticated user's full profile.

curl "https://api.ithbat.io/api/v1/users/me" \
  -H "Authorization: Bearer <access_token>"

Response 200

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tenantId": "3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a",
    "email": "[email protected]",
    "firstName": "Alice",
    "fatherName": "",
    "grandfatherName": "",
    "familyName": "Smith",
    "displayName": "Alice Smith",
    "status": "active",
    "roles": ["admin"],
    "preferences": {
      "theme": "light",
      "language": "en",
      "timezone": "UTC"
    },
    "mfaEnabled": true,
    "metadata": {},
    "externalIds": {},
    "lastLoginAt": "2026-02-24T09:15:00Z",
    "passwordChangedAt": "2026-01-10T14:00:00Z",
    "createdAt": "2025-09-01T08:00:00Z",
    "updatedAt": "2026-02-24T09:15:00Z"
  }
}

PUT /api/v1/users/me

Authentication required.

Update the authenticated user's profile. All fields are optional — only provided fields are updated.

Request Body

Field	Type	Required	Description
`firstName`	string	No	First name
`fatherName`	string	No	Father's name
`grandfatherName`	string	No	Grandfather's name
`familyName`	string	No	Family/last name

curl -X PUT "https://api.ithbat.io/api/v1/users/me" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Alicia",
    "familyName": "Smith-Jones"
  }'

Response 200 — Returns the updated UserResponse object (same shape as GET /users/me).

GET /api/v1/users/me/identities

Authentication required.

List all social identity providers linked to the authenticated user's account.

curl "https://api.ithbat.io/api/v1/users/me/identities" \
  -H "Authorization: Bearer <access_token>"

Response 200

{
  "success": true,
  "data": {
    "identities": [
      {
        "provider": "google",
        "providerUserId": "115789123456789",
        "email": "[email protected]",
        "linkedAt": "2025-10-15T11:00:00Z"
      }
    ]
  }
}

POST /api/v1/users/me/identities/{provider}

Authentication required.

Link a social identity provider to the authenticated user's account.

Path Parameters

Parameter	Type	Description
`provider`	string	Provider name: `google`, `github`, `microsoft`, `apple`

DELETE /api/v1/users/me/identities/{provider}

Authentication required.

Unlink a social identity provider from the authenticated user's account. The user must have a password or at least one other linked provider before unlinking.

GET /api/v1/auth/sessions

Authentication required.

List all active sessions for the authenticated user.

curl "https://api.ithbat.io/api/v1/auth/sessions" \
  -H "Authorization: Bearer <access_token>"

Response 200

{
  "success": true,
  "data": {
    "sessions": [
      {
        "id": "sess_abc123",
        "deviceType": "desktop",
        "deviceName": "Chrome on Windows",
        "ipAddress": "197.134.10.55",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
        "location": {
          "country": "SA",
          "city": "Riyadh",
          "latitude": 24.7136,
          "longitude": 46.6753
        },
        "createdAt": "2026-02-24T09:00:00Z",
        "lastActivity": "2026-02-24T09:15:00Z",
        "isCurrent": true
      }
    ],
    "total": 1
  }
}

DELETE /api/v1/auth/sessions/{id}

Authentication required.

Revoke a specific session by ID. Use GET /api/v1/auth/sessions to list session IDs.

curl -X DELETE "https://api.ithbat.io/api/v1/auth/sessions/sess_abc123" \
  -H "Authorization: Bearer <access_token>"

Response 200

{
  "success": true,
  "message": "Session revoked"
}

DELETE /api/v1/auth/sessions

Authentication required.

Revoke all sessions for the authenticated user except the current one.

curl -X DELETE "https://api.ithbat.io/api/v1/auth/sessions" \
  -H "Authorization: Bearer <access_token>"

Response 200

{
  "success": true,
  "message": "All other sessions revoked"
}

GET /api/v1/users

Permission required: user:read

List all users in the tenant with optional filtering and pagination.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	25	Results per page (max 100)
`search`	string	—	Filter by name or email
`status`	string	—	Filter by status: `active`, `suspended`, `pending`
`roleId`	string	—	Filter by role ID

curl "https://api.ithbat.io/api/v1/users?page=1&limit=25&search=alice" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "data": {
    "users": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "tenantId": "3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a",
        "email": "[email protected]",
        "firstName": "Alice",
        "fatherName": "",
        "grandfatherName": "",
        "familyName": "Smith",
        "displayName": "Alice Smith",
        "status": "active",
        "roles": ["admin"],
        "mfaEnabled": true,
        "lastLoginAt": "2026-02-24T09:15:00Z",
        "createdAt": "2025-09-01T08:00:00Z",
        "updatedAt": "2026-02-24T09:15:00Z"
      }
    ],
    "total": 1
  }
}

GET /api/v1/users/{id}

Permission required: user:read

Retrieve a specific user by their UUID.

curl "https://api.ithbat.io/api/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200 — Returns the full UserResponse object.

Error Codes

Code	HTTP	Description
`RESOURCE_NOT_FOUND`	404	User does not exist in this tenant

POST /api/v1/users

Permission required: user:write

Create a new user in the tenant. Optionally skip email verification for programmatic user creation.

Request Body

Field	Type	Required	Description
`email`	string	Yes	User's email address (must be unique in tenant)
`firstName`	string	Yes	First name
`fatherName`	string	No	Father's name
`grandfatherName`	string	No	Grandfather's name
`familyName`	string	Yes	Family/last name
`password`	string	No	Initial password (auto-generated if omitted)
`skipEmailVerification`	boolean	No	Skip the verification email (default: false)

curl -X POST "https://api.ithbat.io/api/v1/users" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "Carol",
    "familyName": "Williams",
    "skipEmailVerification": true
  }'

Response 201 — Returns the created UserResponse object.

Error Codes

Code	HTTP	Description
`DUPLICATE_EMAIL`	409	A user with this email already exists
`VALIDATION_ERROR`	400	Password does not meet policy requirements

PUT /api/v1/users/{id}

Permission required: user:write

Update a user's profile by ID.

Request Body

Field	Type	Required	Description
`firstName`	string	No	First name
`fatherName`	string	No	Father's name
`grandfatherName`	string	No	Grandfather's name
`familyName`	string	No	Family/last name

curl -X PUT "https://api.ithbat.io/api/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a" \
  -H "Content-Type: application/json" \
  -d '{"firstName": "Alicia"}'

Response 200 — Returns the updated UserResponse object.

DELETE /api/v1/users/{id}

Permission required: user:write

Permanently delete a user and revoke all their active sessions. This action is irreversible.

curl -X DELETE "https://api.ithbat.io/api/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "message": "User deleted"
}

POST /api/v1/users/{id}/suspend

Permission required: user:write

Suspend a user account. Suspended users cannot log in and all active sessions are revoked.

curl -X POST "https://api.ithbat.io/api/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890/suspend" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "message": "User suspended"
}

POST /api/v1/users/{id}/reactivate

Permission required: user:write

Reactivate a previously suspended user account.

curl -X POST "https://api.ithbat.io/api/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890/reactivate" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "message": "User reactivated"
}

POST /api/v1/users/{id}/unlock

Permission required: user:write

Unlock a user account that has been locked after too many failed login attempts.

curl -X POST "https://api.ithbat.io/api/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890/unlock" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "message": "User account unlocked"
}

POST /api/v1/users/{id}/roles

Permission required: role:write

Assign a role to a user.

Request Body

Field	Type	Required	Description
`roleId`	string	Yes	UUID of the role to assign

curl -X POST "https://api.ithbat.io/api/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890/roles" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a" \
  -H "Content-Type: application/json" \
  -d '{"roleId": "r1b2c3d4-e5f6-7890-abcd-ef1234567890"}'

Response 200

{
  "success": true,
  "message": "Role assigned"
}

DELETE /api/v1/users/{id}/roles/{roleId}

Permission required: role:write

Remove a role from a user.

curl -X DELETE "https://api.ithbat.io/api/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890/roles/r1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "message": "Role removed"
}

GET /api/v1/users/{id}/permissions

Permission required: user:read

Get the resolved permission set for a user, including all permissions from all assigned roles.

curl "https://api.ithbat.io/api/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890/permissions" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a"

Response 200

{
  "success": true,
  "data": {
    "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "permissions": [
      "user:read",
      "user:write",
      "role:read",
      "role:write",
      "group:read",
      "group:write",
      "audit:read"
    ]
  }
}

POST /api/v1/users/bulk

Permission required: user:write

Create multiple users in a single request. Up to 1000 users per batch.

Request Body

Field	Type	Required	Description
`users`	array	Yes	Array of `CreateUserRequest` objects (min 1, max 1000)

curl -X POST "https://api.ithbat.io/api/v1/users/bulk" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a" \
  -H "Content-Type: application/json" \
  -d '{
    "users": [
      { "email": "[email protected]", "firstName": "User", "familyName": "One" },
      { "email": "[email protected]", "firstName": "User", "familyName": "Two" }
    ]
  }'

Response 200

{
  "success": true,
  "data": {
    "successful": 2,
    "failed": 0,
    "users": [ ]
  }
}

Partial failures return the same structure with failed > 0 and an errors array:

{
  "success": true,
  "data": {
    "successful": 1,
    "failed": 1,
    "errors": [
      {
        "index": 1,
        "email": "[email protected]",
        "error": "A user with this email already exists",
        "code": "DUPLICATE_EMAIL"
      }
    ],
    "users": [ ]
  }
}

PATCH /api/v1/users/{id}/metadata

Permission required: user:write

Set or merge custom metadata on a user. Useful for storing application-specific attributes.

Request Body

Field	Type	Required	Description
`metadata`	object	Yes	Key-value pairs (values can be any JSON type)

curl -X PATCH "https://api.ithbat.io/api/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890/metadata" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: 3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "department": "Engineering",
      "employeeId": "EMP-0042",
      "costCenter": "CC-101"
    }
  }'

Response 200 — Returns the updated UserResponse object.

GET /api/v1/users/me​

PUT /api/v1/users/me​

GET /api/v1/users/me/identities​

POST /api/v1/users/me/identities/{provider}​

DELETE /api/v1/users/me/identities/{provider}​

GET /api/v1/auth/sessions​

DELETE /api/v1/auth/sessions/{id}​

DELETE /api/v1/auth/sessions​

GET /api/v1/users​

GET /api/v1/users/{id}​

POST /api/v1/users​

PUT /api/v1/users/{id}​

DELETE /api/v1/users/{id}​

POST /api/v1/users/{id}/suspend​

POST /api/v1/users/{id}/reactivate​

POST /api/v1/users/{id}/unlock​

POST /api/v1/users/{id}/roles​

DELETE /api/v1/users/{id}/roles/{roleId}​

GET /api/v1/users/{id}/permissions​

POST /api/v1/users/bulk​

PATCH /api/v1/users/{id}/metadata​

GET /api/v1/users/me

PUT /api/v1/users/me

GET /api/v1/users/me/identities

POST /api/v1/users/me/identities/{provider}

DELETE /api/v1/users/me/identities/{provider}

GET /api/v1/auth/sessions

DELETE /api/v1/auth/sessions/{id}

DELETE /api/v1/auth/sessions

GET /api/v1/users

GET /api/v1/users/{id}

POST /api/v1/users

PUT /api/v1/users/{id}

DELETE /api/v1/users/{id}

POST /api/v1/users/{id}/suspend

POST /api/v1/users/{id}/reactivate

POST /api/v1/users/{id}/unlock

POST /api/v1/users/{id}/roles

DELETE /api/v1/users/{id}/roles/{roleId}

GET /api/v1/users/{id}/permissions

POST /api/v1/users/bulk

PATCH /api/v1/users/{id}/metadata