Skip to content
Torii docs

Update user

PATCH
/api/server/v1/users/{userId}
 
curl --request PATCH \
  --url https://api.torii.so/api/server/v1/users/01931a73-8b00-7000-8000-000000000000 \
  --header 'Content-Type: application/json' \
  --data '{ "firstName": "Ada", "lastName": "Lovelace", "locale": "en", "unsafeMetadata": { "onboardingStep": 2 } }'

Partial update with tri-state PATCH semantics. Every field in UpdateUserRequest is tri-state: omit the key to leave the field unchanged, send a non-null value to set it, or send JSON null to clear it.

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
userId
required
string format: uuid

Identifier of the user to update.

Example 
01931a73-8b00-7000-8000-000000000000

Request Body required

Section titled “Request Body required ”
Media type application/json

PATCH body for updating an end-user. Every field is tri-state: omit the key entirely to leave the field unchanged, send a non-null value to set it, or send JSON null to clear it.

object
firstName

New first (given) name. Send null to clear; omit to leave unchanged.

string | null
Example 
Ada
lastName

New last (family) name. Send null to clear; omit to leave unchanged.

string | null
Example 
Lovelace
locale

New preferred locale. Send null to clear; omit to leave unchanged.

string | null
Allowed values: en da
unsafeMetadata

Deep-merges into the user’s unsafe metadata (a key set to null removes it); omit to leave unchanged. Merged result max 512 bytes.

object
key
additional properties
any
Example 
{
  "onboardingStep": 2
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

The updated user.

Media type application/json

An end-user, including server-only private metadata. Returned only on the secret-key backend API.

object
id
required

Unique identifier for this user.

string format: uuid
environmentId
required

Identifier of the environment this user belongs to.

string format: uuid
name

Full name on the profile, if any.

string | null
firstName

First (given) name on the profile, if any.

string | null
lastName

Last (family) name on the profile, if any.

string | null
locale

Preferred locale for emails and UI messages.

string | null
Allowed values: en da
status
required

Lifecycle status of the user (e.g. active, banned).

string
Allowed values: active banned deleted
createdAt
required

When this user was created (ISO-8601 UTC).

string format: date-time
updatedAt
required

When this user was last modified (ISO-8601 UTC).

string format: date-time
email

Primary email on the profile, if any.

string | null
emailVerifiedAt

When this user’s primary email was verified, if it has been verified.

string | null format: date-time
deletedAt

When this user was deleted, if soft-deleted. Null for active users.

string | null format: date-time
publicMetadata
required

Public metadata: readable by the SDK, writable only server-side.

object
key
additional properties
any
privateMetadata
required

Private metadata: server-only. Never exposed to the SDK or in a JWT.

object
key
additional properties
any
unsafeMetadata
required

Unsafe metadata: readable and writable by the end-user via the SDK.

object
key
additional properties
any
Example 
{
  "id": "01931a73-8b00-7000-8000-000000000000",
  "environmentId": "01931a72-0000-7000-8000-000000000000",
  "name": "Ada Lovelace",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "locale": "en",
  "status": "active",
  "createdAt": "2026-05-16T09:30:00Z",
  "updatedAt": "2026-05-16T10:00:00Z",
  "email": "ada@example.com",
  "emailVerifiedAt": "2026-05-16T09:35:00Z",
  "deletedAt": "2026-05-20T12:00:00Z",
  "publicMetadata": {
    "plan": "pro"
  },
  "privateMetadata": {
    "stripeId": "cus_123"
  },
  "unsafeMetadata": {
    "onboardingStep": 2
  }
}

400

Section titled “400 ”

Invalid body.

Media type application/problem+json
object
type
string format: uri
title
string
status
integer format: int32
detail
string
instance
string format: uri
properties
object
key
additional properties
Example generated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com",
  "properties": {
    "additionalProperty": "example"
  }
}

401

Section titled “401 ”

Missing or invalid secret key.

Media type application/problem+json
object
type
string format: uri
title
string
status
integer format: int32
detail
string
instance
string format: uri
properties
object
key
additional properties
Example generated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com",
  "properties": {
    "additionalProperty": "example"
  }
}

403

Section titled “403 ”

User belongs to a different environment.

Media type application/problem+json
object
type
string format: uri
title
string
status
integer format: int32
detail
string
instance
string format: uri
properties
object
key
additional properties
Example generated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com",
  "properties": {
    "additionalProperty": "example"
  }
}

404

Section titled “404 ”

No user with this id.

Media type application/problem+json
object
type
string format: uri
title
string
status
integer format: int32
detail
string
instance
string format: uri
properties
object
key
additional properties
Example generated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com",
  "properties": {
    "additionalProperty": "example"
  }
}