> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xenia.team/llms.txt
> Use this file to discover all available pages before exploring further.

# Replace User Locations

> Two operations share this endpoint, chosen by which field you send:

- **Replace memberships** — send `locations` (an array of location UUIDs). The user's memberships become exactly that set: anything not listed is removed.
- **Set the default location** — send `defaultLocationId`. Pass `null` or `""` to clear it.

If `defaultLocationId` is present in the body, that branch runs and `locations` is ignored, so do not send both in one call — make two calls.

`location_ids` is accepted as an alias for `locations`, matching the field name used by [Provision Users](/guides/workflows/user-lifecycle).

For API-key callers `locations` **must** be present when you are replacing memberships: an omitted array would otherwise read as "remove everything", so it is rejected instead. Sending an explicit empty array **does** clear every membership. Every id must belong to this workspace, and the target user must already be a member of it.

Requires the **Advanced Location Based Assignment** workspace feature, plus **either** `CAN_ACCESS_LOCATIONS` **or** `CAN_EDIT_LOCATIONS` on the key's user.



## OpenAPI

````yaml PUT /api/v1/mgt/workspaces/{workspaceId}/users/{userId}/locations
openapi: 3.1.0
info:
  title: Xenia Team API - Replace User Locations
  description: >-
    Replaces the full set of locations a user is a member of, or sets that
    user's default location. Use this to keep location membership in sync after
    provisioning, when a manager transfers between sites.
  version: 1.0.0
servers:
  - url: https://api.xenia.team
security: []
paths:
  /api/v1/mgt/workspaces/{workspaceId}/users/{userId}/locations:
    put:
      tags:
        - Users
      summary: Replace User Locations
      description: >-
        Two operations share this endpoint, chosen by which field you send:


        - **Replace memberships** — send `locations` (an array of location
        UUIDs). The user's memberships become exactly that set: anything not
        listed is removed.

        - **Set the default location** — send `defaultLocationId`. Pass `null`
        or `""` to clear it.


        If `defaultLocationId` is present in the body, that branch runs and
        `locations` is ignored, so do not send both in one call — make two
        calls.


        `location_ids` is accepted as an alias for `locations`, matching the
        field name used by [Provision Users](/guides/workflows/user-lifecycle).


        For API-key callers `locations` **must** be present when you are
        replacing memberships: an omitted array would otherwise read as "remove
        everything", so it is rejected instead. Sending an explicit empty array
        **does** clear every membership. Every id must belong to this workspace,
        and the target user must already be a member of it.


        Requires the **Advanced Location Based Assignment** workspace feature,
        plus **either** `CAN_ACCESS_LOCATIONS` **or** `CAN_EDIT_LOCATIONS` on
        the key's user.
      parameters:
        - name: workspaceId
          in: path
          required: true
          description: >-
            UUID of the workspace. Must be the workspace your API key is bound
            to.
          schema:
            type: string
            format: uuid
        - name: userId
          in: path
          required: true
          description: UUID of the user whose location memberships are being replaced.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                locations:
                  type: array
                  description: >-
                    The complete set of location UUIDs the user should belong
                    to. Required for API-key callers when replacing memberships.
                    Also accepted as `location_ids`.
                  items:
                    type: string
                    format: uuid
                defaultLocationId:
                  type:
                    - string
                    - 'null'
                  description: >-
                    Sets the user's default location. Send `null` or `""` to
                    clear it. When this field is present, `locations` is
                    ignored.
            example:
              locations:
                - 8099a742-c9bb-40a7-976e-1963a07e77b6
                - 46715d09-1628-4b1a-a12d-f9e0bbcdbc3c
      responses:
        '200':
          description: >-
            Memberships replaced — `data` is the user's resulting location ids.
            (On a `defaultLocationId` call, `data` is the user's workspace
            membership record instead.)
          content:
            application/json:
              example:
                data:
                  - 8099a742-c9bb-40a7-976e-1963a07e77b6
                  - 46715d09-1628-4b1a-a12d-f9e0bbcdbc3c
                extra_meta:
                  message: ''
        '400':
          description: >-
            Bad Request - `locations` missing for an API-key caller (`locations
            must be an array of location ids.`), the target user is not a member
            of the workspace (`Invalid user_id: …`), or a location id does not
            belong to this workspace (`Invalid location_id: …`). These
            validation failures return `{ "status": false, "message": "…" }`
            rather than the usual error envelope.
        '401':
          description: >-
            Unauthorized - invalid client credentials, or the `workspaceId` in
            the path is not the workspace your key is bound to (`Client does not
            belong to this workspace`).
        '403':
          description: >-
            Forbidden - route not allow-listed for API keys, the key's user
            lacks `CAN_ACCESS_LOCATIONS` / `CAN_EDIT_LOCATIONS`, or the
            workspace lacks the **Advanced Location Based Assignment** feature.
        '422':
          description: >-
            Unprocessable Entity - body failed validation (a `locations` entry
            is not a UUID, unknown field).
        '500':
          description: Internal Server Error.
      security:
        - clientKey: []
          clientSecret: []
components:
  securitySchemes:
    clientKey:
      type: apiKey
      in: header
      name: x-client-key
    clientSecret:
      type: apiKey
      in: header
      name: x-client-secret

````