Skip to main content
The Users API provides methods for managing user accounts, profiles, and onboarding status in Hazel Chat. All methods require authentication.

​
Authentication

All Users API methods require authentication via the AuthMiddleware. Include a valid bearer token in your requests.

​
Methods

​
Get Current User

Retrieve information about the currently authenticated user. 
const client = yield* RpcClient
const currentUser = yield* client["user.me"]()
​
payload
void
No parameters required
​
id
UserId
required
Unique identifier for the user
​
organizationId
OrganizationId | null
ID of the user’s current organization (nullable)
​
role
'admin' | 'member' | 'owner'
required
User’s role in the organization
​
email
string
required
User’s email address
​
firstName
string
User’s first name
​
lastName
string
User’s last name
​
avatarUrl
string
URL to the user’s avatar image
​
isOnboarded
boolean
required
Whether the user has completed onboarding
​
timezone
string | null
User’s timezone (IANA timezone identifier)
​
settings
UserSettings | null
User’s settings object
Errors:
  • UnauthorizedError - User is not authenticated
  • InternalServerError - Unexpected server error

​
Update User

Update an existing user’s profile information. Only users with appropriate permissions can update user data. 
const client = yield* RpcClient

const result = yield* client["user.update"]({
  id: "usr_123",
  firstName: "Jane",
  lastName: "Doe",
  avatarUrl: "https://example.com/avatar.jpg"
})
​
id
UserId
required
ID of the user to update
​
firstName
string
Updated first name
​
lastName
string
Updated last name
​
avatarUrl
string | null
Updated avatar URL (set to null to clear)
​
email
string
Updated email address
​
timezone
string | null
Updated timezone (IANA timezone identifier)
​
settings
UserSettings | null
Updated user settings
​
data
User
required
The updated user object
​
transactionId
TransactionId
required
Transaction ID for optimistic updates
Errors:
  • UserNotFoundError - User with the specified ID doesn’t exist
  • UnauthorizedError - User lacks permission to update this user
  • InternalServerError - Unexpected server error (including WorkOS sync failures)
Implementation Notes:
  • Updates are synchronized with WorkOS user management
  • Changes are performed within a database transaction
  • Policy checks ensure users can only update authorized accounts

​
Delete User

Delete a user account (soft delete). Only users with appropriate permissions can delete users. 
const client = yield* RpcClient

const result = yield* client["user.delete"]({
  id: "usr_123"
})
​
id
UserId
required
ID of the user to delete
​
transactionId
TransactionId
required
Transaction ID for optimistic updates
Errors:
  • UserNotFoundError - User with the specified ID doesn’t exist
  • UnauthorizedError - User lacks permission to delete this user
  • InternalServerError - Unexpected server error (including WorkOS sync failures)
Implementation Notes:
  • Deletion is synchronized with WorkOS user management
  • Changes are performed within a database transaction
  • Policy checks ensure proper authorization

​
Finalize Onboarding

Mark the current authenticated user as having completed onboarding. This sets the isOnboarded flag to true. 
const client = yield* RpcClient

const result = yield* client["user.finalizeOnboarding"]()
​
payload
void
No parameters required
​
data
User
required
The updated user object with isOnboarded set to true
​
transactionId
TransactionId
required
Transaction ID for optimistic updates
Errors:
  • UnauthorizedError - User is not authenticated
  • InternalServerError - Unexpected server error
Implementation Notes:
  • Updates the current authenticated user only
  • Performed within a database transaction
  • No additional permissions required beyond authentication

​
Reset Avatar

Reset the current user’s avatar to their original WorkOS profile picture (e.g., Google/GitHub OAuth avatar). Clears the avatar if WorkOS doesn’t have a profile picture. 
const client = yield* RpcClient

const result = yield* client["user.resetAvatar"]()
​
payload
void
No parameters required
​
data
User
required
The updated user object with the reset avatar
​
transactionId
TransactionId
required
Transaction ID for optimistic updates
Errors:
  • UnauthorizedError - User is not authenticated
  • InternalServerError - Unexpected server error (including WorkOS fetch failures)
Implementation Notes:
  • Fetches the user’s profile picture from WorkOS
  • If WorkOS has a profile picture URL, it’s set as the avatar
  • If no profile picture is available, the avatar is set to null
  • Performed within a database transaction

​
Error Handling

import { Effect } from "effect"
import { RpcClient } from "@hazel/domain/rpc"
import { UserNotFoundError } from "@hazel/domain/rpc"

const updateUserEffect = Effect.gen(function* () {
  const client = yield* RpcClient
  
  const result = yield* client["user.update"]({
    id: "usr_123",
    firstName: "Jane"
  }).pipe(
    Effect.catchTag("UserNotFoundError", (error) =>
      Effect.fail(new Error(`User ${error.userId} not found`))
    ),
    Effect.catchTag("UnauthorizedError", () =>
      Effect.fail(new Error("Not authorized to update this user"))
    )
  )
  
  return result
})

Build docs developers (and LLMs) love

Get started for freeTalk to us