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

# Transfer workspace ownership

> Owner-only ownership transfer, keeping ownerId and member rows disjoint

## Overview

`useTransferWorkspaceOwnership` returns a callable that reassigns a [workspace](/v8/data-models/workspace)'s `ownerId`.

**Authorization:** owner-only. The signed-in user must be this workspace's own owner **or any ancestor owner** — never a capability or reach. (Ancestor-owner transfer is what makes offboarding resolvable: a manager can reassign a departing member's owned sub-workspace without that member's cooperation.)

* The new owner must be a **verified** user in the tenant — they need not already be a member.
* The new owner's existing member row (if any) is removed, keeping `ownerId` and member rows disjoint.
* The previous owner is **demoted** into a fresh member row or **removed**. It defaults to `remove` whenever the field is omitted — on a voluntary self-transfer as much as on an ancestor-owner reassign; pass `"demote"` to keep them on the roster. On demote, rank defaults to **one rung below you** — `0` when you are apex (the usual case), or one below your own row if you are an ancestor owner who also sits in this workspace's ladder.

## Usage Example

```tsx theme={null}
import { useTransferWorkspaceOwnership } from "@sublay/react-js";

function TransferOwnership({ workspaceId }: { workspaceId: string }) {
  const transferWorkspaceOwnership = useTransferWorkspaceOwnership();

  const handleTransfer = async (newOwnerId: string) => {
    const workspace = await transferWorkspaceOwnership({
      workspaceId,
      newOwnerId,
      previousOwnerDisposition: "demote",
      previousOwnerRank: 0,
      previousOwnerCapabilities: ["view"],
    });
    console.log("New owner:", workspace.ownerId);
  };
}
```

## Parameters

<ParamField path="workspaceId" type="string" required>
  The workspace UUID.
</ParamField>

<ParamField path="newOwnerId" type="string" required>
  The new owner — any **verified** user in the tenant. This is the transfer **target**, not an acting user.
</ParamField>

<ParamField path="previousOwnerDisposition" type="&#x22;demote&#x22; | &#x22;remove&#x22;">
  What happens to the outgoing owner. Defaults to `remove` when omitted, on every path.
</ParamField>

<ParamField path="previousOwnerRank" type="number">
  On demote, the ex-owner's rank. **Absolute only** — no relative form. Defaults to **one rung below your own anchor**: `0` when you are apex (an owner or ancestor owner with no member row here), or `yourRank + 1` when you do hold a row here, so the default never seats the outgoing owner above you. An explicit value is honored verbatim.
</ParamField>

<ParamField path="previousOwnerCapabilities" type="WorkspaceCapability[]">
  On demote, the ex-owner's capabilities.
</ParamField>

## Returns

Returns the updated [Workspace](/v8/data-models/workspace) object with the new `ownerId`.

## Error codes

| Code | Status | Meaning |
| - | - | - |
| `workspace/unauthorized` | 403 | You are not the owner or an ancestor owner. |
| `workspace/email-not-verified` | 403 | The new owner has no verified email. |
| `workspace/invalid-target` | 404 | The target user does not exist. |

## Related

* [Transfer Ownership API](/v8/api-reference/workspaces/transfer-ownership)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.