Update the current user's preferences
Updates the calling user's preferences. Today only timezone
(an IANA timezone name such as America/New_York) is mutable;
future per-user preference keys land here without a new route.
Pass preferences.timezone: null to clear a previously set
timezone, the read surface then renders it as null and the
FE falls back to the browser's resolved timezone. A PATCH with
an empty body is a no-op and returns the current state.
Only Clerk-authenticated callers may use this endpoint. API-key
principals receive 403 FORBIDDEN because api keys are not
user-scoped, so there is no "owning user" to persist against.
Returns the full Me payload so the FE can use the response as
a refresh.
Authorization
clerkJWT First-party clients (the dashboard) authenticate with the session token issued at sign-in. Requests are scoped to the active organization and the signed-in user's role.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/v1/me" \ -H "Content-Type: application/json" \ -d '{ "preferences": { "timezone": "America/Los_Angeles" } }'{
"success": true,
"error": {
"code": "string",
"message": "string",
"request_id": "string",
"details": {
"property1": "string",
"property2": "string"
}
},
"meta": {
"total": 0,
"limit": 0,
"offset": 0,
"next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNC0yNlQxMjowMDowMFoiLCJpZCI6IjAxOTAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMSJ9",
"last_event_at": "2019-08-24T14:15:22Z"
},
"data": {
"user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
"org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
"is_staff": true,
"scopes": [
"string"
],
"preferences": {
"timezone": "America/New_York"
}
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "authentication failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "api keys cannot update user preferences",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "INVALID_TIMEZONE",
"message": "invalid timezone",
"details": {
"timezone": "unknown IANA timezone"
},
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}