--- title: "Update user by external ID" method: PATCH path: "/api/v1/users:external/{external_id}" tags: ["Users"] --- # Update user by external ID `PATCH /api/v1/users:external/{external_id}` Modifies user account information for a user identified by your application's external identifier. Use this endpoint to keep user profile data in sync from your system without needing to store Scalekit's internal user ID. You can update the user's profile, phone number, and metadata fields. ## Path parameters - `external_id` string, required ## Request body - V1usersUpdateUser - `external_id` string — Your application's unique identifier for this user, used to link Scalekit with your system. - `metadata` object — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). - `user_profile` UsersUpdateUserProfile - `custom_attributes` object — Updates custom attributes for extended user profile data and application-specific information. Use this field to store business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. - `family_name` string — Updates the user's family name (last name or surname). Use this field to modify how the user's last name appears throughout the system. Maximum 255 characters allowed. - `first_name` string — [DEPRECATED] Use given_name instead. User's given name. Maximum 200 characters. - `gender` string — Updates the user's gender identity information. Use this field to store the user's gender identity for personalization, compliance, or reporting purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies. - `given_name` string — Updates the user's given name (first name). Use this field to modify how the user's first name appears in the system and user interfaces. Maximum 255 characters allowed. - `groups` string[] — Updates the list of group names the user belongs to within the organization. Use this field to manage the user's group memberships for role-based access control, team assignments, or organizational structure. Groups are typically used for permission management and collaborative access. Each group name must be unique within the list, 1-250 characters long, with a maximum of 50 groups per user. - `last_name` string — [DEPRECATED] Use family_name instead. User's family name. Maximum 200 characters. - `locale` string — Updates the user's preferred language and region settings using BCP-47 format codes. Use this field to customize the user's experience with localized content, date formats, number formatting, and UI language. When not specified, the user inherits the organization's default locale settings. Common values include `en-US`, `en-GB`, `fr-FR`, `de-DE`, and `es-ES`. - `metadata` object — Updates system-managed key-value pairs for internal tracking and operational data. Use this field to store system-generated metadata like account status, signup source, last activity tracking, or integration-specific identifiers. These fields are typically managed by automated processes rather than direct user input. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. - `name` string — Updates the user's complete display name. Use this field when you want to set the full name as a single string rather than using separate given and family names. This name appears in user interfaces, reports, and anywhere a formatted display name is needed. - `phone_number` string — Updates the user's phone number in E.164 international format. Use this field to enable SMS-based authentication methods, two-factor authentication, or phone-based account recovery. The phone number must include the country code and be formatted according to E.164 standards (e.g., `+1` for US numbers). This field is required when enabling SMS authentication features. - `picture` string — Updates the URL to the user's profile picture or avatar image. Use this field to set or change the user's profile photo that appears in user interfaces, directory listings, and collaborative features. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. Maximum URL length is 2048 characters. - `preferred_username` string — Updates the user's preferred username for display and identification purposes. Use this field to set a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, and informal communications. Maximum 512 characters allowed. ## Response `200` User updated successfully. Returns the modified user object with updated timestamps. - UsersUpdateUserResponse - `user` UsersUser - `create_time` string, date-time — Timestamp when the user account was initially created. Automatically set by the server. - `email` string — Primary email address for the user. Must be unique across the environment and valid per RFC 5322. - `external_id` string — Your application's unique identifier for this organization, used to link Scalekit with your system. - `id` string — Unique system-generated identifier for the user. Immutable once created. - `last_login_time` string, date-time — Timestamp of the user's most recent successful authentication. Updated automatically. - `memberships` CommonsOrganizationMembership[] — List of organization memberships. Automatically populated based on group assignments. - `accepted_at` string, date-time — Timestamp when the user accepted the invitation. - `created_at` string, date-time — Timestamp when the invitation was created. - `display_name` string — Organization display name. This field stores a user-friendly name for the organization that may be different from the formal name, often used for UI display purposes. - `expires_at` string, date-time — Timestamp when the invitation expired. - `inviter_email` string — ID of the user who invited this user. - `join_time` string, date-time — Timestamp when the membership was created. Automatically set by the server. - `membership_status` 'ACTIVE' | 'INACTIVE' | 'PENDING_INVITE' | 'INVITE_EXPIRED' - `metadata` object — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). - `name` string — Organization name. This field stores the formal organization name used for identification and display purposes. - `organization_id` string — Unique identifier for the organization. Immutable and read-only. - `permissions` string[] — Effective permissions granted to the user within the organization (including inherited permissions from assigned roles). Lists the specific actions and access rights the user can perform. - `provisioning_method` string — How the user was provisioned. Possible values: - `jit_using_sso` (Just-in-time provisioning during SSO login) - `allowed_email_domain` (User joined via allowed email domain matching) - `org_creator` (User created the organization) - `direct_provision` (User was directly provisioned via API or SCIM) - `invitation` (User was invited and accepted an invitation) - `roles` CommonsRole[] - `display_name` string — Human-readable name for the role - `id` string — Role ID - `name` string — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions. - `metadata` object — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars). - `update_time` string, date-time — Timestamp of the last modification to the user account. Automatically updated by the server. - `user_profile` CommonsUserProfile - `custom_attributes` object — Custom attributes for extended user profile data and application-specific information. This field stores business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users for personalization and business logic. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. - `email_verified` boolean — Indicates if the user's email address has been verified. Automatically updated by the system. - `external_identities` CommonsExternalIdentity[] — List of external identity connections associated with the user profile. - `connection_id` string — Unique identifier for the external identity connection. Immutable and read-only. - `connection_provider` 'OKTA' | 'GOOGLE' | 'MICROSOFT_AD' | 'AUTH0' | 'ONELOGIN' | 'PING_IDENTITY' | 'JUMPCLOUD' | 'CUSTOM' | 'GITHUB' | 'GITLAB' | 'LINKEDIN' | 'SALESFORCE' | 'MICROSOFT' | 'IDP_SIMULATOR' | 'SCALEKIT' | 'ADFS' - `connection_type` string — Name of the external identity connection. - `connection_user_id` string — Unique identifier for the user in the external identity provider system. Immutable and read-only. - `created_time` string, date-time — Timestamp when this external identity connection was first created. Immutable and read-only. - `is_social` boolean — Indicates if the identity provider is a social provider (true) or enterprise/custom provider (false). Read-only. - `last_login_time` string, date-time — Timestamp of the user's last successful login via this external identity provider. Automatically updated by the system. - `last_synced_time` string, date-time — Timestamp of the last data synchronization for this external identity from the provider. Automatically updated by the system. - `family_name` string — The user's family name (last name or surname). This field stores the user's last name and is combined with the given name to create the full display name. The family name is used in formal communications, user listings, and organizational directories throughout the system. Maximum 255 characters allowed. - `gender` string — The user's gender identity information. This field stores the user's gender identity for personalization, compliance reporting, or organizational analytics purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies and applicable regulations. - `given_name` string — The user's given name (first name). This field stores the user's first name and is used for personalization, display purposes, and when generating the full display name. The given name appears in user interfaces, formal communications, and user listings throughout the system. Maximum 255 characters allowed. - `groups` string[] — The list of group names the user belongs to within the organization. This field stores the user's group memberships for role-based access control, team assignments, and organizational structure. Groups are typically used for permission management, collaborative access, and organizational hierarchy. Each group name represents a distinct organizational unit or team that the user is associated with. - `id` string — Unique system-generated identifier for the user profile. Immutable and read-only. - `locale` string — The user's preferred language and region settings using BCP-47 format codes. This field customizes the user's experience with localized content, date formats, number formatting, and UI language throughout the system. When not specified, the user inherits the organization's default locale settings. Common values include `en-US`, `en-GB`, `fr-FR`, `de-DE`, and `es-ES`. - `metadata` object — Raw attributes received from identity providers during authentication. This field stores the original user profile data as received from external IdP systems (SAML, OIDC, etc.) including provider-specific claims and attributes. These fields preserve the complete set of attributes received from the identity source and are used for mapping, synchronization, and audit purposes. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs. - `name` string — The user's complete display name in formatted form. This field stores the full name as a single string and is typically used when you want to set the complete name rather than using separate given and family names. This name appears in user interfaces, reports, directory listings, and anywhere a formatted display name is needed. This field serves as a formatted display name that complements the individual given_name and family_name fields. - `phone_number` string — The user's phone number in E.164 international format. This field stores the phone number for user contact and identification purposes. The phone number must include the country code and be formatted according to E.164 standards (e.g., `+1` for US numbers). This field is optional. - `phone_number_verified` boolean — Indicates if the user's phone number has been verified. Automatically updated by the system. - `picture` string — The URL to the user's profile picture or avatar image. This field stores the location of the user's profile photo that appears in user interfaces, directory listings, and collaborative features throughout the system. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. This image is used for visual identification and personalization across the platform. - `preferred_username` string — The user's preferred username for display and identification purposes. This field stores a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, informal communications, and collaborative features throughout the system. Maximum 512 characters allowed. --- [API](https://skmtc.net/scalekit/apis/scalekit-api-reference.md) · [All operations](https://skmtc.net/scalekit/apis/scalekit-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/scalekit/scalekit-api-reference/versions/a40d5d4650e5/schema)