Users

Users represent the people who interact with your ITSM platform — agents who resolve tickets, admins who configure the system, and end users who submit requests. Every user belongs to an organization (tenant) and is assigned a role that governs their permissions through RBAC. On this page, we'll dive into the different user endpoints you can use to list, create, update, and deactivate users programmatically.

The user model

The user model contains all the information about an ITSM platform user, including their profile, role-based access control assignment, MFA status, and organizational membership.

Properties

Name
id
Type
string
Description
Unique identifier for the user (UUID).
Name
email
Type
string
Description
The user's email address, unique within the organization.
Name
name
Type
string
Description
Display name shown throughout the platform.
Name
first_name
Type
string
Description
The user's first name.
Name
last_name
Type
string
Description
The user's last name.
Name
role
Type
string
Description
The RBAC role assigned to the user. One of super_admin, org_admin, manager, agent, viewer, or api_service.
Name
status
Type
string
Description
Current account status. One of active, inactive, or suspended.
Name
department
Type
string
Description
The department the user belongs to (e.g., IT Operations, HR, Engineering).
Name
avatar_url
Type
string
Description
URL to the user's avatar image.
Name
mfa_enabled
Type
boolean
Description
Whether multi-factor authentication is enabled for this user.
Name
locale
Type
string
Description
The user's preferred locale (e.g., en-US).
Name
timezone
Type
string
Description
The user's preferred timezone (e.g., America/New_York).
Name
last_login_at
Type
timestamp
Description
Timestamp of the user's most recent login.
Name
created_at
Type
timestamp
Description
Timestamp of when the user was created.
Name
updated_at
Type
timestamp
Description
Timestamp of when the user was last updated.
Name
organization_id
Type
string
Description
The tenant ID that the user belongs to.

RBAC roles

Role	Description
`super_admin`	Full platform access across all tenants. Can manage organizations, billing, and global settings.
`org_admin`	Full access within a single organization. Can manage users, teams, and configuration.
`manager`	Can manage team members, view reports, and approve changes.
`agent`	Can work tickets, access the knowledge base, and view user details.
`viewer`	Read-only access to tickets and dashboards.
`api_service`	Machine-to-machine access for integrations and automation.

GET/v1/users

List all users

This endpoint allows you to retrieve a paginated list of all users in your organization. By default, a maximum of twenty users are shown per page. You can filter by role, status, and department, and search by name or email.

Optional attributes

Name
role
Type
string
Description
Filter users by RBAC role (e.g., agent, org_admin).
Name
status
Type
string
Description
Filter users by account status (e.g., active, suspended).
Name
department
Type
string
Description
Filter users by department.
Name
search
Type
string
Description
Search users by name or email (case-insensitive partial match).
Name
page
Type
integer
Description
The page number for pagination. Defaults to 1.
Name
limit
Type
integer
Description
Limit the number of users returned per page. Defaults to 20, maximum 100.

Request

GET

/v1/users

curl -G http://localhost:3000/v1/users \
  -H "Authorization: Bearer {token}" \
  -d role=agent \
  -d status=active \
  -d limit=10

Response

{
  "success": true,
  "data": [
    {
      "id": "usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "email": "jchen@acme.com",
      "name": "Jessica Chen",
      "first_name": "Jessica",
      "last_name": "Chen",
      "avatar_url": "https://cdn.example.com/avatars/jchen.jpg",
      "role": "agent",
      "department": "IT Operations",
      "status": "active",
      "created_at": 1708783200
    },
    {
      "id": "usr_b2c3d4e5-f6a7-8901-bcde-f12345678901"
      // ...
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 34,
      "totalPages": 4,
      "hasMore": true
    }
  }
}

POST/v1/users

Create a user

This endpoint allows you to create a new user in your organization. You must provide an email address at minimum. The system will generate a display name from the email if one is not provided. The user is created with active status and the default user role unless specified otherwise.

Required attributes

Name
email
Type
string
Description
The email address for the new user. Must be unique within the organization.

Optional attributes

Name
first_name
Type
string
Description
The user's first name.
Name
last_name
Type
string
Description
The user's last name.
Name
display_name
Type
string
Description
Display name. Defaults to first_name last_name or the email prefix.
Name
role
Type
string
Description
RBAC role to assign. One of admin, agent, user, or readonly. Defaults to user.
Name
department
Type
string
Description
The department the user belongs to.

Request

POST

/v1/users

curl http://localhost:3000/v1/users \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "mwilson@acme.com",
    "first_name": "Marcus",
    "last_name": "Wilson",
    "role": "agent",
    "department": "Network Operations"
  }'

Response

{
  "success": true,
  "data": {
    "id": "usr_c3d4e5f6-a7b8-9012-cdef-123456789012",
    "email": "mwilson@acme.com",
    "name": "Marcus Wilson",
    "first_name": "Marcus",
    "last_name": "Wilson",
    "avatar_url": null,
    "role": "agent",
    "department": "Network Operations",
    "status": "active",
    "created_at": 1708790400
  }
}

GET/v1/users/:id

Retrieve a user

This endpoint allows you to retrieve a user by providing their UUID. Refer to the list at the top of this page to see which properties are included with user objects.

Request

GET

/v1/users/usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890

curl http://localhost:3000/v1/users/usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "data": {
    "id": "usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email": "jchen@acme.com",
    "name": "Jessica Chen",
    "first_name": "Jessica",
    "last_name": "Chen",
    "role": "agent",
    "status": "active",
    "department": "IT Operations",
    "avatar_url": "https://cdn.example.com/avatars/jchen.jpg",
    "mfa_enabled": true,
    "locale": "en-US",
    "timezone": "America/Chicago",
    "last_login_at": 1708784100,
    "created_at": 1708783200,
    "updated_at": 1708784100,
    "organization_id": "org_9f8e7d6c5b4a"
  }
}

GET/v1/users/me

Get current user

This endpoint returns the profile of the currently authenticated user based on the JWT token. It includes the user's role, permissions, tenant context, and preference settings. This is typically the first call made after authentication to populate the frontend session.

Request

GET

/v1/users/me

curl http://localhost:3000/v1/users/me \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "data": {
    "id": "usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email": "jchen@acme.com",
    "name": "Jessica Chen",
    "firstName": "Jessica",
    "lastName": "Chen",
    "role": "agent",
    "permissions": ["tickets:*", "knowledge:read", "users:read"],
    "avatarUrl": "https://cdn.example.com/avatars/jchen.jpg",
    "tenantId": "org_9f8e7d6c5b4a",
    "tenantSlug": "acme",
    "mfaEnabled": true,
    "department": "IT Operations",
    "locale": "en-US",
    "timezone": "America/Chicago"
  }
}

PATCH/v1/users/:id

Update a user

This endpoint allows you to perform a partial update on a user. You can update profile fields such as name, department, locale, and timezone. To change a user's role, use the dedicated change role endpoint.

Optional attributes

Name
first_name
Type
string
Description
Update the user's first name.
Name
last_name
Type
string
Description
Update the user's last name.
Name
display_name
Type
string
Description
Update the user's display name.
Name
department
Type
string
Description
Update the user's department.
Name
bio
Type
string
Description
Update the user's bio / description.
Name
locale
Type
string
Description
Update the user's preferred locale.
Name
timezone
Type
string
Description
Update the user's preferred timezone.
Name
avatar_url
Type
string
Description
Update the user's avatar image URL.

Request

PATCH

/v1/users/usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890

curl -X PATCH http://localhost:3000/v1/users/usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "department": "Security Operations",
    "timezone": "America/New_York"
  }'

Response

{
  "success": true,
  "data": {
    "id": "usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email": "jchen@acme.com",
    "name": "Jessica Chen",
    "firstName": "Jessica",
    "lastName": "Chen",
    "role": "agent",
    "permissions": ["tickets:*", "knowledge:read", "users:read"],
    "avatarUrl": "https://cdn.example.com/avatars/jchen.jpg",
    "tenantId": "org_9f8e7d6c5b4a",
    "tenantSlug": "acme",
    "mfaEnabled": true,
    "department": "Security Operations",
    "locale": "en-US",
    "timezone": "America/New_York"
  }
}

PUT/v1/users/:id/role

Change user role

This endpoint allows an organization admin to change a user's RBAC role. This is a privileged operation that requires org_admin or super_admin role. Changing a role immediately updates the user's permissions across the platform.

Required attributes

Name
role
Type
string
Description
The new role to assign. One of org_admin, manager, agent, viewer, or api_service.

Request

PUT

/v1/users/usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890/role

curl -X PUT http://localhost:3000/v1/users/usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890/role \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "manager"
  }'

Response

{
  "success": true,
  "data": {
    "id": "usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email": "jchen@acme.com",
    "name": "Jessica Chen",
    "role": "manager",
    "status": "active",
    "updated_at": 1708790500
  }
}

DELETE/v1/users/:id

Deactivate a user

This endpoint allows you to deactivate a user. Deactivation is a soft-delete operation: the user's status is set to inactive and they can no longer authenticate, but their data is preserved for audit trail purposes. Any tickets currently assigned to the deactivated user will need to be reassigned. To permanently remove a user's data, contact your platform administrator.

Request

DELETE

/v1/users/usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890

curl -X DELETE http://localhost:3000/v1/users/usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer {token}"