Skip to main content
Most user-related endpoints are covered in the Authentication section. This page documents additional user operations.

​
User Object

The user object is returned by various endpoints: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "name": "John Doe",
  "profileImage": "/uploads/profiles/avatar.jpg",
  "isAdmin": false,
  "status": "active",
  "createdAt": "2026-03-02T10:30:00.000Z",
  "updatedAt": "2026-03-02T10:30:00.000Z"
}
​
id
string
Unique user UUID
​
email
string
User’s email address (unique)
​
name
string
User’s display name (max 100 characters)
​
profileImage
string
Relative URL to profile image, or null if not set
​
isAdmin
boolean
Whether user has admin privileges
​
status
enum
User account status:
  • active - Normal active user
  • pending - Awaiting admin approval
​
createdAt
string
ISO 8601 timestamp of account creation
​
updatedAt
string
ISO 8601 timestamp of last update
The password, apiToken, and oidcSubject fields are never returned by the API for security reasons.

​
Get Current User

See Authentication - Get Current User 
curl -X GET http://localhost:3001/api/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Update Profile

See Authentication - Update Profile 
curl -X PATCH http://localhost:3001/api/auth/profile \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe"
  }'

​
Profile Image Management

​
Upload Profile Image

See Authentication - Upload Profile Image 
curl -X POST http://localhost:3001/api/auth/profile/image \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "image=@/path/to/image.jpg"

​
Delete Profile Image

See Authentication - Delete Profile Image 
curl -X DELETE http://localhost:3001/api/auth/profile/image \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Change Password

See Authentication - Change Password 
curl -X POST http://localhost:3001/api/auth/change-password \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "currentPassword": "oldpassword123",
    "newPassword": "newpassword456"
  }'

​
User Status

​
Active Users

Active users have full access to the application:
  • Can log in and receive tokens
  • Can create and manage notes
  • Can share notes with other users
  • Can access all user features

​
Pending Users

When registration mode is set to review, new users are created with pending status:
  • Cannot log in until approved by admin
  • Do not receive access tokens on registration
  • Must wait for admin approval
  • Receive error on login attempt
Login error for pending users: 
{
  "statusCode": 403,
  "message": "Account is pending approval",
  "error": "Forbidden"
}
Admins can approve pending users via the Admin API.

​
Admin Users

​
First User

The first user to register automatically becomes an admin:
  • isAdmin: true is set automatically
  • No additional configuration needed
  • Cannot be changed via user endpoints

​
Admin Privileges

Admin users have access to:
  • Admin API endpoints
  • User management functions
  • System settings configuration
  • Registration mode control
  • OIDC settings management
Admin status can only be modified via the Admin API.

​
User Discovery

There is no public user directory or search endpoint. Users can discover others by:
  1. Email-based sharing: Knowing the exact user UUID (typically obtained through admin panel or prior interaction)
  2. Admin panel: Admins can view all users via Admin - List Users
For production deployments, consider implementing a user search endpoint if you need to enable easy user discovery for sharing notes.

​
Profile Images

​
Storage

Profile images are stored in /data/uploads/profiles/ and served at /uploads/profiles/: 
http://localhost:3001/uploads/profiles/550e8400-1234-5678-9abc-def012345678.jpg

​
Constraints

  • Max file size: 5MB
  • Allowed formats: JPEG, PNG, WebP
  • Validation: File type validated on server

​
File naming

Images are renamed on upload: 
{user-uuid}.{extension}
Example: 
550e8400-e29b-41d4-a716-446655440000.jpg
This ensures:
  • One image per user (uploading new image replaces old)
  • No filename conflicts
  • Simple cleanup on user deletion

​
OIDC Authentication

​
OIDC Users

Users can authenticate via OIDC providers when configured:
  • oidcSubject field stores the provider’s subject identifier
  • password field is null for OIDC-only users
  • Cannot use password-based login
  • Cannot change password via API

​
Hybrid Users

Users can have both password and OIDC authentication:
  • Created with password initially
  • Later linked to OIDC provider
  • Can authenticate using either method
  • Can change password even with OIDC linked
OIDC configuration is managed via the Admin API.

​
Data Privacy

User data is protected:
  • Passwords are hashed with bcrypt (10 rounds)
  • API tokens are unique and revocable
  • Refresh tokens are stored securely and expire after 90 days
  • Email addresses are unique and case-sensitive
  • No public user directory exists

​
Account Deletion

Only admins can delete users via Admin - Delete User. When a user is deleted:
  • All owned notes are deleted (cascade)
  • All tags are deleted (cascade)
  • All shares created by user are deleted (cascade)
  • All shares to user are deleted (cascade)
  • All refresh tokens are deleted (cascade)
  • Profile image is removed from filesystem
User deletion is permanent and cannot be undone. All associated data is permanently deleted.

​
Search Users

​
Search for Users

​
GET /api/users/search
endpoint
Search for users by name or email. Used for finding users to share notes with.
Authentication: Required (JWT)
​
q
string
required
Search query string (searches both name and email fields)
curl -X GET "http://localhost:3001/api/users/search?q=john" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]",
    "name": "John Doe",
    "profileImage": "/uploads/profiles/john.jpg"
  },
  {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "email": "[email protected]",
    "name": "Johnny Smith",
    "profileImage": null
  }
]
​
id
string
User UUID
​
email
string
User’s email address
​
name
string
User’s display name
​
profileImage
string
Relative URL to profile image, or null if not set
  • Search is case-insensitive and matches partial strings
  • Results exclude the requesting user
  • Only active users are returned (pending users are excluded)
  • Maximum 50 results returned

Build docs developers (and LLMs) love

Get started for freeTalk to us