PUT /api/v1/apps/:appUuid/users/:userUuidOrEmail

Modifies an existing users resource.

This endpoint documentation is generated from the current Fastify route implementation and should be treated as the implementation-level contract for this version of the API.

Source route file: src/api/routes/external/private/apiKey/app/users/put.ts

Request Method

PUT

Base URL

https://api.userdocks.local:5000

Endpoint

/api/v1/apps/:appUuid/users/:userUuidOrEmail

Path Variables

Variable	Type	Required	Description
appUuid	string	true	Path variable from route pattern.
userUuidOrEmail	string	true	Path variable from route pattern.

Query Parameters

Variable	Type	Required	Description
language	string	true	Query parameter parsed by route handler.
invitationTenantUuid	string	false	Query parameter parsed by route handler.

HTTP Headers

Variable	Type	Required	Description
x-api-key	string	true	API key value for the app.
x-client-id	string	true	Must match :appUuid path variable.
x-api-key-type	string	true	Use read for GET and write for POST/PUT/DELETE.
Content-Type	string	true	Use application/json for JSON request bodies.

Request Body

Runtime type reference: updateUserWithApiKeySchema (same shape as updateUserWithBearerSchema).

{
  "givenName": "Jane",
  "familyName": "Doe",
  "phoneNumber": "+491234567890",
  "locale": "en",
  "addresses": [
    {
      "typeUuid": "11111111-1111-1111-1111-111111111111",
      "name": "billing",
      "addressLineOne": "Main Street 1",
      "locality": "Berlin",
      "region": "Berlin",
      "countryUuid": "11111111-1111-1111-1111-111111111111",
      "postalCode": "10115"
    }
  ]
}

Successful Response

Success status code(s): 200.

{
  "kind": "users",
  "totalItems": 1,
  "itemsLength": 1,
  "items": [
    {
      "uuid": "user_11111111-1111-1111-1111-111111111111",
      "email": "user@example.com",
      "sub": "auth0|user_11111111",
      "name": "Jane Doe",
      "givenName": "Jane",
      "familyName": "Doe",
      "middleName": null,
      "nickname": "jane",
      "preferredUsername": "jane.doe",
      "profile": "https://example.com/users/jane",
      "picture": "https://example.com/assets/jane.png",
      "website": "https://example.com",
      "emailVerified": true,
      "gender": "female",
      "birthdate": "1990-01-01",
      "zoneinfo": "Europe/Berlin",
      "locale": "en",
      "phoneNumber": "+491234567890",
      "phoneNumberVerified": true,
      "referrer": "campaign-abc",
      "referralCode": "ref_11111111",
      "preferredLanguageUuid": "lang_11111111-1111-1111-1111-111111111111",
      "isDisabled": false,
      "appUuid": "app_11111111-1111-1111-1111-111111111111",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "userTags": [
        {
          "tag": {
            "uuid": "tag_11111111-1111-1111-1111-111111111111",
            "appUuid": "app_11111111-1111-1111-1111-111111111111",
            "name": "beta-user",
            "description": "User belongs to beta segment",
            "createdAt": "2026-01-01T00:00:00.000Z",
            "updatedAt": "2026-01-01T00:00:00.000Z"
          }
        }
      ],
      "addresses": [
        {
          "uuid": "addr_11111111-1111-1111-1111-111111111111",
          "name": "billing",
          "addressLineOne": "Main Street 1",
          "addressLineTwo": "Floor 3",
          "postalCode": "10115",
          "locality": "Berlin",
          "region": "Berlin",
          "country": "DE",
          "type": "business",
          "updatedAt": "2026-01-01T00:00:00.000Z"
        }
      ],
      "tenantsAsAdmin": [
        {
          "tenant": {
            "uuid": "tenant_11111111-1111-1111-1111-111111111111",
            "name": "Acme Tenant",
            "isDisabled": false,
            "createdAt": "2026-01-01T00:00:00.000Z",
            "updatedAt": "2026-01-01T00:00:00.000Z"
          }
        }
      ],
      "tenantsAsUser": [
        {
          "tenant": {
            "uuid": "tenant_11111111-1111-1111-1111-111111111111",
            "name": "Acme Tenant",
            "isDisabled": false,
            "createdAt": "2026-01-01T00:00:00.000Z",
            "updatedAt": "2026-01-01T00:00:00.000Z"
          }
        }
      ]
    }
  ]
}

Error Responses

HTTP Status	Example Error
401	{"errors":[{"validation":"error","code":"[E4010]","message":"Unauthorized Token or API key"}]}
401	{"errors":[{"validation":"error","code":"[E4011]","message":"Unauthorized API key type"}]}
403	{"errors":[{"validation":"error","code":"[E4030]","message":"App Is Disabled"}]}
400	{"errors":[{"validation":"error","code":"[E4000]","message":"Bad Request / validation error"}]}
500	{"errors":[{"validation":"error","code":"[E0000]","message":"Internal Server Error"}]}

Example

const query = new URLSearchParams({
  language: 'en',
  invitationTenantUuid: 'invitationTenantUuid-value',
});
const url = `https://api.userdocks.local:5000/api/v1/apps/appUuid-value/users/user@example.com?${query.toString()}`;

const response = await fetch(url, {
  method: 'PUT',
  headers: {
    'x-api-key': '<api-key>',
    'x-client-id': 'appUuid-value',
    'x-api-key-type': 'write',
    'Content-Type': 'application/json',
  },
  body: '{"givenName":"Jane","familyName":"Doe","phoneNumber":"+491234567890","locale":"en","addresses":[{"typeUuid":"11111111-1111-1111-1111-111111111111","name":"billing","addressLineOne":"Main Street 1","locality":"Berlin","region":"Berlin","countryUuid":"11111111-1111-1111-1111-111111111111","postalCode":"10115"}]}',
});
const data = await response.json();
console.log(response.status, data);