Update user

Updates a user. Only the values provided will be updated.

PATCH /users/{user_id}

Update user

cURL

curl --request PATCH \
  --url https://api.stack-auth.com/api/v1/users/{user_id} \
  --header 'Content-Type: application/json' \
  --data '
{
  "display_name": "John Doe",
  "profile_image_url": "https://example.com/image.jpg",
  "client_metadata": {
    "key": "value"
  },
  "client_read_only_metadata": {
    "key": "value"
  },
  "server_metadata": {
    "key": "value"
  },
  "primary_email": "[e-mail]",
  "primary_email_verified": true,
  "primary_email_auth_enabled": true,
  "password": "my-new-password",
  "totp_secret_base64": "dG90cC1zZWNyZXQ=",
  "selected_team_id": "team-id",
  "restricted_by_admin": false,
  "restricted_by_admin_reason": null,
  "restricted_by_admin_private_details": null,
  "country_code": "US"
}
'

200

{
  "id": "3241a285-8329-4d69-8f3d-316e08cf140c",
  "primary_email_verified": true,
  "primary_email_auth_enabled": true,
  "signed_up_at_millis": 1630000000000,
  "last_active_at_millis": 1630000000000,
  "is_anonymous": true,
  "is_restricted": false,
  "restricted_by_admin": false,
  "risk_scores": {
    "sign_up": {
      "bot": 0,
      "free_trial_abuse": 0
    }
  },
  "primary_email": "[e-mail]",
  "display_name": "John Doe",
  "selected_team": {
    "created_at_millis": 1630000000000,
    "id": "ad962777-8244-496a-b6a2-e0c6a449c79e",
    "display_name": "My Team",
    "server_metadata": {
      "key": "value"
    },
    "profile_image_url": "https://example.com/image.jpg",
    "client_metadata": {
      "key": "value"
    },
    "client_read_only_metadata": {
      "key": "value"
    }
  },
  "selected_team_id": "team-id",
  "profile_image_url": "https://example.com/image.jpg",
  "client_metadata": {
    "key": "value"
  },
  "client_read_only_metadata": {
    "key": "value"
  },
  "server_metadata": {
    "key": "value"
  },
  "restricted_reason": null,
  "restricted_by_admin_reason": null,
  "restricted_by_admin_private_details": null,
  "country_code": "US"
}

Path Parameters

user_id · string · required

The ID of the user, or the special value me for the currently authenticated user

Example:

"3241a285-8329-4d69-8f3d-316e08cf140c"

Body

application/json

display_name · string

Human-readable user display name. This is not a unique identifier.

Example:

"John Doe"

profile_image_url · string

URL of the profile image for user. Can be a Base64 encoded image. Must be smaller than 100KB. Please compress and crop to a square before passing in.

Example:

"https://example.com/image.jpg"

client_metadata · object

Client metadata. Used as a data store, accessible from the client side. Do not store information that should not be exposed to the client.

Example:

{ "key": "value" }

client_read_only_metadata · object

Client read-only, server-writable metadata. Used as a data store, accessible from the client side. Do not store information that should not be exposed to the client. The client can read this data, but cannot modify it. This is useful for things like subscription status.

Example:

{ "key": "value" }

server_metadata · object

Server metadata. Used as a data store, only accessible from the server side. You can store secret information related to the user here.

Example:

{ "key": "value" }

primary_email · string

Primary email

Example:

"[e-mail]"

primary_email_verified · boolean

Whether the primary email has been verified to belong to this user

Example:

true

primary_email_auth_enabled · boolean

Whether the primary email is used for authentication. If this is set to false, the user will not be able to sign in with the primary email with password or OTP

Example:

true

password · string

Sets the user's password. Doing so revokes all current sessions.

Example:

"my-new-password"

password_hash · string

If password is not given, sets the user's password hash to the given string in Modular Crypt Format (ex.: $2a$10$VIhIOofSMqGdGlL4wzE//e.77dAQGqNtF/1dT7bqCrVtQuInWy2qi). Doing so revokes all current sessions.

totp_secret_base64 · string

Enables 2FA and sets a TOTP secret for the user. Set to null to disable 2FA.

Example:

"dG90cC1zZWNyZXQ="

selected_team_id · string

ID of the team currently selected by the user

Example:

"team-id"

is_anonymous · boolean

restricted_by_admin · boolean

Whether the user is restricted by an administrator. Can be set manually or by sign-up rules.

Example:

false

restricted_by_admin_reason · string

Public reason shown to the user explaining why they are restricted. Optional.

Example:

null

restricted_by_admin_private_details · string

Private details about the restriction (e.g., which sign-up rule triggered). Only visible to server access and above.

Example:

null

country_code · string

Best-effort ISO country code captured at sign-up time from request geo headers.

Example:

"US"

risk_scores · object

Show child attributes

Response

200 - application/json

Successful response

id · string · required

The unique identifier of the user

Example:

"3241a285-8329-4d69-8f3d-316e08cf140c"

primary_email_verified · boolean · required

Whether the primary email has been verified to belong to this user

Example:

true

primary_email_auth_enabled · boolean · required

Whether the primary email is used for authentication. If this is set to false, the user will not be able to sign in with the primary email with password or OTP

Example:

true

signed_up_at_millis · number · required

The time the user signed up (identify) => (the number of milliseconds since epoch, January 1, 1970, UTC)

Example:

1630000000000

last_active_at_millis · number · required

The time the user was last active (identify) => (the number of milliseconds since epoch, January 1, 1970, UTC)

Example:

1630000000000

is_anonymous · boolean · required

is_restricted · boolean · required

Whether the user is in restricted state (has signed up but not completed onboarding requirements)

Example:

false

restricted_by_admin · boolean · required

Whether the user is restricted by an administrator. Can be set manually or by sign-up rules.

Example:

false

risk_scores · object · required

User risk scores used for sign-up risk evaluation.

Show child attributes

Example:

{
  "sign_up": { "bot": 0, "free_trial_abuse": 0 }
}

primary_email · string

Primary email

Example:

"[e-mail]"

display_name · string

Human-readable user display name. This is not a unique identifier.

Example:

"John Doe"

selected_team · object

Show child attributes

selected_team_id · string

ID of the team currently selected by the user

Example:

"team-id"

profile_image_url · string

URL of the profile image for user. Can be a Base64 encoded image. Must be smaller than 100KB. Please compress and crop to a square before passing in.

Example:

"https://example.com/image.jpg"

client_metadata · object

Client metadata. Used as a data store, accessible from the client side. Do not store information that should not be exposed to the client.

Example:

{ "key": "value" }

client_read_only_metadata · object

Client read-only, server-writable metadata. Used as a data store, accessible from the client side. Do not store information that should not be exposed to the client. The client can read this data, but cannot modify it. This is useful for things like subscription status.

Example:

{ "key": "value" }

server_metadata · object

Server metadata. Used as a data store, only accessible from the server side. You can store secret information related to the user here.

Example:

{ "key": "value" }

restricted_reason · object

The reason why the user is restricted (e.g., type: "email_not_verified", "anonymous", or "restricted_by_administrator"), null if not restricted

Show child attributes

Example:

null

restricted_by_admin_reason · string

Public reason shown to the user explaining why they are restricted. Optional.

Example:

null

restricted_by_admin_private_details · string

Private details about the restriction (e.g., which sign-up rule triggered). Only visible to server access and above.

Example:

null

country_code · string

Best-effort ISO country code captured at sign-up time from request geo headers.

Example:

"US"