Update User Profile Information

Update user profile information including system fields (email, mobile, name, etc.) and custom fields. This guide covers field permissions, update methods, and API usage.

Purpose and Benefits

What is User Profile Update?

User profile updates allow users and administrators to modify user account information, including:

User Identification Attributes: email, username, etc.
User Communication Attributes: mobile number, email address
User Descriptive Attributes: first name, last name, etc.
Custom Fields: Business-specific fields configured in field settings

Key Benefits

Benefit	Description
Self-Service Updates	Users can update their own profile information
Admin Management	Administrators can update any user's profile
Field-Level Control	Granular permissions control what can be updated
Instant Updates	Changes take effect immediately (when verification not required)
Custom Fields Support	Update business-specific custom fields

Update Methods

cidaas supports different methods for updating user profiles:

Method	Endpoint	Scope	Use Case
User Self-Service	`PUT /users-srv/user/profile/{sub}`	`profile`	User updates own profile
Admin Update	`PUT /user-srv/users/{sub}`	`cidaas:users_write`	Admin updates any user profile
Email/Mobile with OTP	`PUT /useractions-srv/communication/medium/{sub}`	`profile`	Secure email/mobile change with verification
Admin Email/Mobile	`POST /useractions-srv/communication/medium/{sub}`	`cidaas:users_write`	Admin-initiated email/mobile change via link

Prerequisites

Before updating user profiles:

✅ User authentication token (for self-service updates)
✅ Admin token with cidaas:users_write scope (for admin updates)
✅ Required roles: ADMIN, SECONDARY_ADMIN, SUPER_ADMIN, or USER_CREATE (for admin updates)
✅ Field permissions configured in Field Settings

User Profile Update Flow

The following sequence diagram illustrates the user profile update process:

Flow Steps Explained

Authenticate Request
- User/Admin provides authentication token
- System validates token and extracts user permissions
- User Self-Service: Token sub must match path sub
- Backendside Update / Admin update: Token must have cidaas:users_write scope or admin roles
Validate Field Permissions
- System checks field permissions from Field Settings
- Validates if field is enabled, read-only, internal, or requires verification
- API Reference: See Field Settings API for field configuration
Check Communication Medium Settings
- For email/mobile updates, system checks verificationForMedium configuration
- If verificationForMedium is set, standard update API is blocked
- Must use OTP verification flow instead
Update User Profile
- System validates field values (format, uniqueness, etc.)
- Updates user account and social identity records
- Applies changes to custom fields if provided
Create Webhook Events (if applicable)
- For email changes: Creates EMAIL_CHANGED fact event
- For other significant changes: Creates appropriate fact events
- API Reference: See Update User API for admin updates

Important Details

Required Permissions

User Self-Service Update

Endpoint: PUT /users-srv/user/profile/{sub}
API Reference: PUT /users-srv/user/profile/:sub

Key Requirements:

Scope: profile scope required in the access token
Access Control: User can only update their own profile - the token's sub must match the path parameter {sub}
Field Restrictions: Subject to field permissions (read-only and internal fields cannot be updated by users)

What Can Be Updated:

System fields: given_name, family_name, email, mobile_number, birthdate, locale, address, etc.
Custom fields: Provided in the customFields object (must be pre-configured in Field Settings)
Identity-specific fields: Use identityId to specify which identity to update

Important Notes:

Email/mobile changes may require OTP verification if verificationForMedium is configured in Field Settings
Read-only fields are visible but cannot be modified by users (admins can update them)
Internal fields are not accessible via this endpoint

For detailed request/response schemas, error codes, and examples, see the API Reference.

Admin Update

Endpoint: PUT /user-srv/users/{sub}

Scope: cidaas:users_write
Roles: ADMIN, SECONDARY_ADMIN, SUPER_ADMIN, or USER_CREATE
Groups: Member of CIDAAS_ADMINS group
Access Control: Admin can update any user's profile

Field Permissions

Field permissions in Field Settings control update behavior:

Permission	Description	User Can Update	Admin Can Update	API Behavior
Enable	Field is editable and visible	Yes	Yes	Field can be updated via profile update API
Required	Field is mandatory	Yes	Yes	Field must be provided; update fails if missing
Read Only	Field value can only be viewed, not changed	No	Yes	User update API rejects changes; Admin can update
Internal	Field is internal and not visible to users	No	Yes	Field not returned in userinfo; Admin can update via API
verificationForMedium	Requires verification before changing communication medium	No (via update API)	Yes (via update API)	Update API blocked; Must use OTP verification flow

Instant Email/Mobile Change (Without Verification)

When verificationForMedium is NOT set for email or mobile number fields, these fields can be updated instantly via the standard profile update API:

User Self-Service:

PUT /users-srv/user/profile/{sub}
Authorization: Bearer {user_token}
{
  "email": "[email protected]",
  "given_name": "John",
  "family_name": "Doe"
}

Admin Update:

PUT /user-srv/users/{sub}
Authorization: Bearer {admin_token}
{
  "userData": {
    "email": "[email protected]",
    "given_name": "John",
    "family_name": "Doe"
  }
}

Important Considerations:

No confirmation is sent to the old email/mobile
No verification code is required
Changes take effect immediately
Use only when you have proper access controls and trust the update source

Email/Mobile Change with Verification

When verificationForMedium=[email, mobile_number] is configured, the standard profile update API cannot change email or mobile number. You must use the OTP verification flow:

User Profile Update (Logged-in Users):

PUT /useractions-srv/communication/medium/{sub}?action=initiate
{
  "medium": "email",
  "value": "[email protected]"
}

During Verification Flow (trackId): If a user needs to change their email/mobile during registration or login verification, use the trackId-based flow:

POST /useractions-srv/communication/medium/track/{trackId}?action=initiate
{
  "medium": "email",
  "value": "[email protected]"
}

Webhooks and Facts

When user profile is updated, fact events may be automatically created and sent as webhooks:

Event Type	Object Type	Object ID	Description	When Triggered	Webhook Attributes
EMAIL_CHANGED	`users`	`sub` (user ID)	Email address was changed	Email updated via profile update API	`["email", "email_verified"]` or `["identity_id", "sub"]`

Note: Webhook events are only created for significant changes (e.g., email changes). Not all profile updates trigger webhooks.

Field Validation

The system validates field values during updates:

Format Validation: Email format, mobile number format (E164), date formats, etc.
Uniqueness Validation: Unique fields (email, username, etc.) must not conflict with existing users
Required Fields: Required fields must be provided
Field Type Validation: Values must match the configured field data type

Custom Fields

Custom fields can be updated by providing them in the customFields object:

{
  "customFields": {
    "employee_id": "EMP12345",
    "department": "Engineering",
    "hire_date": "2024-01-15"
  }
}

Note: Custom fields must be pre-configured in Field Settings.

Technical Integration

Endpoint	Method	Description	Link
Update User Profile (Self-Service)	PUT	User updates own profile	PUT /users-srv/user/profile/:sub
Update User (Admin)	PUT	Admin updates any user profile	PUT /user-srv/users/:sub
Get User Info	GET	Retrieve user profile information	GET /users-srv/userinfo
Get User by Sub	GET	Admin retrieves user by sub	GET /user-srv/users/:sub
Get Public Fields	GET	Get list of configurable fields	GET /fieldsetup-srv/public/fields

Topic	Description	Link
Email/Mobile Change with OTP	Secure communication medium updates with verification	Email/Mobile Change
Admin Email/Mobile Change	Admin-initiated email/mobile change via link	Admin Email/Mobile Change
Communication Change During Verification	Change email/mobile during registration/login using trackId	Communication Change During Verification
Field Settings	Configure field permissions and settings	Field Settings
Account Structure	Understand user data model	Account Structure
User Status	Manage user account status	User Status

Need Support?

Please contact us directly on our support page.

Purpose and Benefits​

What is User Profile Update?​

Key Benefits​

Update Methods​

Prerequisites​

User Profile Update Flow​

Flow Steps Explained​

Important Details​

Required Permissions​

User Self-Service Update​

Admin Update​

Field Permissions​

Instant Email/Mobile Change (Without Verification)​

Email/Mobile Change with Verification​

Webhooks and Facts​

Field Validation​

Custom Fields​

Technical Integration​

Related Topics​

Need Support?​