User Preferences

Overview

User Preferences allow you to manage your personal profile information and password. These are user-specific settings that apply only to your account, as opposed to organization-wide settings.

Authentication required: All endpoints require user authentication (valid access token).These endpoints operate on the authenticated user’s profile only. No special permissions required beyond being logged in.

API Endpoints

Get My Profile

Retrieve your own profile information:

GET /users/me
Headers:
  Authorization: Bearer {accessToken}

Response:

{
  "message": "User profile fetched successfully",
  "user": {
    "id": "user-123",
    "name": "John Doe",
    "phone": "+250781234567",
    "email": "john.doe@example.com",
    "profilePhotoUrl": "https://example.com/photos/john.jpg",
    "createdAt": "2025-01-15T10:30:00.000Z"
  }
}

Update My Profile

Update your profile information:

PUT /users/me
Headers:
  Authorization: Bearer {accessToken}
Body:
{
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phone": "+250781234567",
  "profilePhotoUrl": "https://example.com/photos/john.jpg"
}

Request body fields:

Field	Type	Required	Validation	Description
`name`	string	No	-	Display name
`email`	string	No	Valid email format	Email address
`phone`	string	No	Rwandan phone number (+250…)	Phone number
`profilePhotoUrl`	string	No	Valid URL	Profile photo URL

All fields are optional - include only fields you want to update. Response:

{
  "message": "User updated successfully",
  "user": {
    "id": "user-123",
    "name": "John Doe",
    "phone": "+250781234567",
    "email": "john.doe@example.com",
    "profilePhotoUrl": "https://example.com/photos/john.jpg"
  }
}

Error cases:

Status	Message	Cause
401	”User not found”	Invalid token or user deleted
409	”User with that email or phone already exists”	Email/phone conflict with another user

Change Password

Update your password:

POST /users/change-password
Headers:
  Authorization: Bearer {accessToken}
Body:
{
  "oldPassword": "current-password",
  "newPassword": "new-password"
}

Request body fields:

Field	Type	Required	Validation	Description
`oldPassword`	string	Yes	Must match current password	Current password for verification
`newPassword`	string	Yes	Minimum 6 characters	New password

Response:

{
  "message": "Password changed successfully."
}

Error cases:

Status	Message	Cause
401	”User not found”	Invalid token or user deleted
401	”User has no password set”	Account created without password
401	”Invalid old password”	Incorrect current password

Important: After password change, existing sessions remain valid. User is NOT logged out automatically.

Editable Profile Fields

Name

Field: name Description: Your display name shown throughout the application Example: “John Doe” Usage:

Appears on transaction records
Shown in audit logs
Displayed to other organization members

Recommendation: Use your real name for accountability

Email Address

Field: email Description: Email address for notifications and login Format: Valid email format Example: “john.doe@example.com” Usage:

Login identifier (in addition to phone)
Email notification recipient (if organization has email enabled)
Password reset destination

Validation: Must be unique across all users in Agatabo (not just your organization) Important: Changing email does not require re-verification. New email becomes active immediately.

Phone Number

Field: phone Description: Phone number for SMS notifications and login Format: Rwandan phone number in international format Example: “+250781234567” Validation:

Must start with “+250”
Must be valid Rwandan number format
Must be unique across all users

Usage:

Login identifier (in addition to email)
SMS notification recipient (if organization has SMS enabled)
Password reset destination (via SMS)

Recommendation: Keep phone number up-to-date for account recovery

Profile Photo

Field: profilePhotoUrl Description: URL to your profile photo Format: Valid URL (http or https) Example: “https://example.com/photos/profile.jpg” Usage:

Displayed in navigation bar
Shown in user menus

Note: Agatabo does not host photos. You must provide a URL to an externally-hosted image.

Password

Updated via: POST /users/change-password (separate endpoint) Requirements:

Minimum 6 characters
Must provide current password for verification

Best practices:

Use mix of letters, numbers, and symbols
Don’t reuse passwords from other services
Use password manager for strong passwords
Change password if you suspect unauthorized access

Security: Passwords are hashed using bcrypt. Never stored or transmitted in plain text.

Immutable Fields

These fields CANNOT be changed by users:

User ID

Field: id Description: System-generated unique identifier Example: “user-abc123” Usage: Internal database references, API parameters

Created At

Field: createdAt Description: Account creation timestamp Format: ISO 8601 datetime Example: “2025-01-15T10:30:00.000Z”

Organization-Level Settings

The following are NOT user preferences (controlled at organization level):

Notification Preferences

Current limitation: Users CANNOT opt out of individual notification types. How it works:

Organization administrator enables/disables email notifications for entire organization
Organization administrator enables/disables SMS notifications for entire organization
If enabled, ALL users with email/phone receive notifications

Workaround (not recommended):

Remove email/phone from profile to stop receiving notifications
This affects login capability (you’ll only be able to use remaining identifier)

See: Organization Settings

Display Preferences

Currently NOT available: The following features do not exist at user or organization level:

Language selection (system uses browser language)
Theme (light/dark mode)
Custom date/time format (uses organization setting)
Dashboard layout customization
Report default filters
Timezone preference (uses organization timezone)

These may be added in future versions.

Common Use Cases

Update Your Email

API call:

curl -X PUT "/users/me" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newemail@example.com"
  }'

Result: Email updated immediately. No verification email sent. Important:

Ensure you have access to new email (for future password resets)
New email must not be used by another account

Update Phone Number

API call:

curl -X PUT "/users/me" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+250787654321"
  }'

Phone format:

Must start with “+250”
Must be valid Rwandan phone number
Example: “+250781234567”

Validation error if:

Phone doesn’t match Rwandan format
Phone already used by another account

Change Password

API call:

curl -X POST "/users/change-password" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "oldPassword": "current-password",
    "newPassword": "new-strong-password-123"
  }'

Result: Password changed immediately. Existing sessions remain valid. Security note: Sessions are NOT automatically invalidated. User remains logged in on all devices.

Update Multiple Fields at Once

API call:

curl -X PUT "/users/me" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane.smith@example.com",
    "phone": "+250781234567",
    "profilePhotoUrl": "https://example.com/jane.jpg"
  }'

All fields optional - include only what you want to update.

Password Reset Flow

If you forgot your password:

Step 1: Request Reset

API endpoint:

POST /users/reset-password
Body:
{
  "identifier": "john.doe@example.com"
}

identifier can be:

Email address
Phone number (starting with ”+”)

Response:

{
  "message": "If an account with that identifier exists, a password reset link has been sent."
}

What happens:

If identifier is email: Password reset link sent via email
If identifier is phone: Password reset link sent via SMS
If identifier doesn’t exist: Same message returned (security - don’t reveal account existence)

Email example: Subject: “Reset your Agatabo password” Body: “Reset your Agatabo password: https://app.agatabo.com/auth/reset-password?token=abc123xyz…”

Step 2: Confirm Reset

After clicking reset link, submit new password:

POST /users/reset-password/confirm
Body:
{
  "token": "abc123xyz",
  "newPassword": "new-password-here"
}

Response:

{
  "message": "Password reset successfully",
  "accessToken": "eyJhbGc...",
  "refreshToken": "eyJhbGc...",
  "user": {
    "id": "user-123",
    "name": "John Doe",
    "phone": "+250781234567",
    "email": "john.doe@example.com",
    "profilePhotoUrl": "https://example.com/photos/john.jpg",
    "userType": "user"
  }
}

Important:

All existing sessions are invalidated (logged out on all devices)
New session created automatically (user logged in)
Reset token can only be used once

Best Practices

Managing your user preferences:Profile updates:

✅ Keep email and phone current for account recovery
✅ Use real name for accountability
✅ Verify email/phone change immediately (test notifications)
✅ Update profile photo from reliable hosting (not temporary links)

Password security:

✅ Use minimum 10 characters (even though system allows 6)
✅ Include mix of uppercase, lowercase, numbers, symbols
✅ Use unique password (not reused from other sites)
✅ Use password manager (LastPass, 1Password, Bitwarden)
✅ Change password if suspicious activity detected

Email/phone uniqueness:

✅ One email = one Agatabo account (cannot share across accounts)
✅ One phone = one Agatabo account
✅ To use same email/phone elsewhere, remove from current account first

Password reset:

✅ Check spam folder if reset email not received
✅ Wait 5 minutes before requesting another reset
✅ Contact administrator if reset emails not arriving
✅ Reset token expires after limited time (use promptly)

Privacy:

✅ Your name visible to other organization members
✅ Email/phone visible to organization administrators
✅ Password never visible to anyone (encrypted)
✅ Profile photo should not contain sensitive information

Troubleshooting

Q: Email/phone change says “already exists” A: Error: “User with that email or phone already exists” Cause: Another user account already has that email or phone. Solution:

Use different email/phone
If you own the other account, remove email/phone from that account first
Contact administrator if email/phone incorrectly assigned elsewhere

Q: Password change says “invalid old password” A: Error: “Invalid old password” Cause: Current password entered incorrectly. Solution:

Verify current password (check Caps Lock, keyboard layout)
If truly forgotten, use password reset flow instead
Contact administrator if account locked

Q: Profile update doesn’t reflect immediately A: Check:

Did request succeed? (200 response)
Try logging out and back in
Clear browser cache
Check if you’re viewing cached data

Q: Can I use email/phone from deleted account? A: Depends on implementation. If user account was deleted:

Email/phone may become available again
May require administrator intervention
Contact support if error persists

Q: Want to disable notifications just for me A: Not possible. Notifications are organization-wide settings. Options:

Ask administrator to disable notifications for entire organization
Remove your email/phone (affects login capability - not recommended)

See: Organization Settings

Q: Password reset email not received A: Check:

Spam/junk folder
Email address correct (no typos)
Organization has email service configured
Wait 5 minutes (email delivery may be delayed)

Contact administrator if still not received.

Q: Want to change timezone/date format A: These are organization-level settings, not user preferences. Contact administrator with settings:write permission. See: Organization Settings

Organization Settings

Organization-wide configuration

Managing Members

Update member information (for admins)

Permissions

Access control and roles

Audit Trail

Track profile changes

​Overview

​API Endpoints

​Get My Profile

​Update My Profile

​Change Password

​Editable Profile Fields

​Name

​Email Address

​Phone Number

​Profile Photo

​Password

​Immutable Fields

​User ID

​Created At

​Organization-Level Settings

​Notification Preferences

​Display Preferences

​Common Use Cases

​Update Your Email

​Update Phone Number

​Change Password

​Update Multiple Fields at Once

​Password Reset Flow

​Step 1: Request Reset

​Step 2: Confirm Reset

​Best Practices

​Troubleshooting

​Related Topics

Organization Settings

Managing Members

Permissions

Audit Trail

Overview

API Endpoints

Get My Profile

Update My Profile

Change Password

Editable Profile Fields

Name

Email Address

Phone Number

Profile Photo

Password

Immutable Fields

User ID

Created At

Organization-Level Settings

Notification Preferences

Display Preferences

Common Use Cases

Update Your Email

Update Phone Number

Change Password

Update Multiple Fields at Once

Password Reset Flow

Step 1: Request Reset

Step 2: Confirm Reset

Best Practices

Troubleshooting

Related Topics