Users

Manage organization users, roles, and group/application assignments.

GET/api/v1/usersList organization usersBearer Token▾

Returns a paginated list of users belonging to the current organization. Supports filtering by search term, role, and status.

Parameters

Name	Type	Required	Description
`search`	string	Optional	Search term to filter users by name or email.e.g. `alice`
`role`	string	Optional	Filter users by organization role.e.g. `admin` `owneradminmemberviewer`
`status`	string	Optional	Filter users by account status.e.g. `active`
`page`	number	Optional	Page number for pagination (1-indexed).e.g. `1`
`limit`	number	Optional	Number of results per page.e.g. `20`

Response Fields

Name	Type	Required	Description
`data`	User[]	Optional	Array of user records for the current page.
`total`	number	Optional	Total number of users matching the query.
`page`	number	Optional	Current page number.
`limit`	number	Optional	Number of results per page.

Response Example

{
  "data": [
    {
      "id": "usr_01hx9z1q2w3e4r5t6y7u",
      "email": "alice@example.com",
      "firstName": "Alice",
      "lastName": "Nguyen",
      "role": "admin",
      "status": "active",
      "createdAt": "2024-01-15T09:30:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20
}

Code Examples

curl -X GET "https://api.sutraid.com/api/v1/users?page=1&limit=20" \
  -H "Authorization: Bearer <your_token>" \
  -H "x-org-id: <your_org_id>"

POST/api/v1/usersCreate user in organizationBearer Token▾

Creates a new user account within the organization. Optionally assigns the user to groups and applications during creation.

Request Body

Name	Type	Required	Description
`email`	string	Required	Email address of the new user.e.g. `bob@example.com`
`firstName`	string	Optional	First name of the user.e.g. `Bob`
`lastName`	string	Optional	Last name of the user.e.g. `Smith`
`role`	string	Optional	Organization role to assign to the user.e.g. `member` `owneradminmemberviewer`
`groupIds`	string[]	Optional	Array of group UUIDs to assign the user to at creation.e.g. `["grp_01hx9z1q2w3e4r5t6y7u"]`
`applicationIds`	string[]	Optional	Array of application UUIDs the user should have access to.e.g. `["app_01hx9z1q2w3e4r5t6y7u"]`
`onboardingMethod`	string	Optional	Method used to onboard the user (e.g. magic_link, password).e.g. `magic_link`
`temporaryPassword`	string	Optional	Temporary password for password-based onboarding. User will be prompted to change on first login.e.g. `Temp@12345`

Response Fields

Name	Type	Required	Description
`id`	string	Optional	Unique identifier of the created user.
`email`	string	Optional	Email address of the user.
`firstName`	string	Optional	First name.
`lastName`	string	Optional	Last name.
`role`	string	Optional	Assigned organization role.
`status`	string	Optional	Account status.
`createdAt`	string	Optional	ISO 8601 creation timestamp.

Response Example

{
  "id": "usr_01hx9z1q2w3e4r5t6y7v",
  "email": "bob@example.com",
  "firstName": "Bob",
  "lastName": "Smith",
  "role": "member",
  "status": "pending",
  "createdAt": "2024-06-01T12:00:00Z"
}

Code Examples

curl -X POST "https://api.sutraid.com/api/v1/users" \
  -H "Authorization: Bearer <your_token>" \
  -H "x-org-id: <your_org_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "bob@example.com",
    "firstName": "Bob",
    "lastName": "Smith",
    "role": "member",
    "onboardingMethod": "magic_link"
  }'

PUT/api/v1/users/:idUpdate userBearer Token▾

Updates the profile, role, status, or assignments of an existing user in the organization.

Parameters

Name	Type	Required	Description
`id`	string (UUID)	Required	Unique identifier of the user to update.e.g. `usr_01hx9z1q2w3e4r5t6y7u`

Request Body

Name	Type	Required	Description
`firstName`	string	Optional	Updated first name.e.g. `Alice`
`lastName`	string	Optional	Updated last name.e.g. `Johnson`
`role`	string	Optional	New organization role for the user.e.g. `admin` `owneradminmemberviewer`
`status`	string	Optional	New account status (e.g. active, suspended).e.g. `active`
`groupIds`	string[]	Optional	Replaces the user's group memberships with this list.e.g. `["grp_01hx9z1q2w3e4r5t6y7u"]`
`applicationIds`	string[]	Optional	Replaces the user's application assignments with this list.e.g. `["app_01hx9z1q2w3e4r5t6y7u"]`

Response Fields

Name	Type	Required	Description
`id`	string	Optional	User identifier.
`email`	string	Optional	Email address.
`firstName`	string	Optional	Updated first name.
`lastName`	string	Optional	Updated last name.
`role`	string	Optional	Updated organization role.
`status`	string	Optional	Updated account status.
`updatedAt`	string	Optional	ISO 8601 timestamp of last update.

Response Example

{
  "id": "usr_01hx9z1q2w3e4r5t6y7u",
  "email": "alice@example.com",
  "firstName": "Alice",
  "lastName": "Johnson",
  "role": "admin",
  "status": "active",
  "updatedAt": "2024-06-01T14:00:00Z"
}

Code Examples

curl -X PUT "https://api.sutraid.com/api/v1/users/usr_01hx9z1q2w3e4r5t6y7u" \
  -H "Authorization: Bearer <your_token>" \
  -H "x-org-id: <your_org_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Alice",
    "lastName": "Johnson",
    "role": "admin",
    "status": "active"
  }'

DELETE/api/v1/users/:idDelete userBearer Token▾

Permanently removes a user from the organization. This action cannot be undone.

Parameters

Name	Type	Required	Description
`id`	string (UUID)	Required	Unique identifier of the user to delete.e.g. `usr_01hx9z1q2w3e4r5t6y7u`

Response Fields

Name	Type	Required	Description
`message`	string	Optional	Confirmation message.e.g. `User deleted`

Response Example

{
  "message": "User deleted"
}

Code Examples

curl -X DELETE "https://api.sutraid.com/api/v1/users/usr_01hx9z1q2w3e4r5t6y7u" \
  -H "Authorization: Bearer <your_token>" \
  -H "x-org-id: <your_org_id>"

PUT/api/v1/users/:id/groupsAssign groups to userBearer Token▾

Replaces all group memberships for a user with the provided list of group IDs.

Parameters

Name	Type	Required	Description
`id`	string (UUID)	Required	Unique identifier of the user.e.g. `usr_01hx9z1q2w3e4r5t6y7u`

Request Body

Name	Type	Required	Description
`groupIds`	string[]	Required	Array of group UUIDs to assign to the user. Replaces existing group memberships.e.g. `["grp_01hx9z1q2w3e4r5t6y7u", "grp_02hx9z1q2w3e4r5t6y7v"]`

Response Fields

Name	Type	Required	Description
`id`	string	Optional	User identifier.
`groups`	Group[]	Optional	Updated list of groups the user belongs to.

Response Example

{
  "id": "usr_01hx9z1q2w3e4r5t6y7u",
  "groups": [
    {
      "id": "grp_01hx9z1q2w3e4r5t6y7u",
      "name": "Engineering"
    },
    {
      "id": "grp_02hx9z1q2w3e4r5t6y7v",
      "name": "Admins"
    }
  ]
}

Code Examples

curl -X PUT "https://api.sutraid.com/api/v1/users/usr_01hx9z1q2w3e4r5t6y7u/groups" \
  -H "Authorization: Bearer <your_token>" \
  -H "x-org-id: <your_org_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "groupIds": [
      "grp_01hx9z1q2w3e4r5t6y7u",
      "grp_02hx9z1q2w3e4r5t6y7v"
    ]
  }'

PUT/api/v1/users/:id/applicationsAssign applications to userBearer Token▾

Replaces all application assignments for a user with the provided list of application IDs.

Parameters

Name	Type	Required	Description
`id`	string (UUID)	Required	Unique identifier of the user.e.g. `usr_01hx9z1q2w3e4r5t6y7u`

Request Body

Name	Type	Required	Description
`applicationIds`	string[]	Required	Array of application UUIDs to assign to the user. Replaces existing application assignments.e.g. `["app_01hx9z1q2w3e4r5t6y7u", "app_02hx9z1q2w3e4r5t6y7v"]`

Response Fields

Name	Type	Required	Description
`id`	string	Optional	User identifier.
`applications`	Application[]	Optional	Updated list of applications assigned to the user.

Response Example

{
  "id": "usr_01hx9z1q2w3e4r5t6y7u",
  "applications": [
    {
      "id": "app_01hx9z1q2w3e4r5t6y7u",
      "name": "Acme CRM"
    },
    {
      "id": "app_02hx9z1q2w3e4r5t6y7v",
      "name": "Internal Dashboard"
    }
  ]
}

Code Examples

curl -X PUT "https://api.sutraid.com/api/v1/users/usr_01hx9z1q2w3e4r5t6y7u/applications" \
  -H "Authorization: Bearer <your_token>" \
  -H "x-org-id: <your_org_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationIds": [
      "app_01hx9z1q2w3e4r5t6y7u",
      "app_02hx9z1q2w3e4r5t6y7v"
    ]
  }'