---
title: Shares and Ownership
path: core-concepts/shares-and-ownership
status: published
---

A **share** is the collaboration unit in ScaiDrive — a namespace that holds files and folders and has a defined set of members. Every file and every folder lives inside exactly one share.

## Share types

Three share types, distinguished by intent:

| Type | Purpose | Typical ownership |
|------|---------|-------------------|
| `central` | Organization-wide shared drives (Engineering, Legal, Marketing) | Group |
| `personal` | A user's private drive | User |
| `project` | Cross-functional collaboration on a bounded scope | User or group |

Functionally, all three types are the same shape — they're shares with an owner, members, a quota, and contents. The type is a hint to the UI and reporting, not a functional distinction.

## The owner

Every share has exactly one `owner_id`. The owner is either a user (`usr_...`) or a group (`grp_...`). A group-owned share survives its creator leaving the organization — anyone in the owning group has owner-level rights.

Ownership can be transferred:

```bash
curl -X POST $SCAIDRIVE_URL/api/v1/permissions/ownership/share/shr_01J3K/transfer \
  -H "Authorization: Bearer $SCAIDRIVE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"new_owner_id": "grp_01J3L"}'
```

Transfers require the current owner's consent (the request must be authenticated as the current owner or a tenant admin).

## Members and roles

A share has zero or more **members**. Each member is a principal (user or group) with one of four roles:

| Role | Permissions |
|------|-------------|
| `owner` | Full control. Can modify members, transfer ownership, delete the share |
| `admin` | Can modify members. Cannot transfer ownership or delete the share |
| `contributor` | Can read, create, modify, delete content |
| `reader` | Read-only access to content |

Roles at the share level define the **baseline permissions** for every file and folder inside. ACLs can refine this per resource — see [Permissions and ACLs](/docs/scaidrive/core-concepts/permissions-and-acls).

Members are added via the members API:

```bash
curl -X POST $SCAIDRIVE_URL/api/v1/shares/shr_01J3K/members \
  -H "Authorization: Bearer $SCAIDRIVE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "principal_type": "user",
    "principal_id": "usr_01J4M",
    "role": "contributor"
  }'
```

A member can have an `expires_at` for time-bounded access — useful for contractors.

## Group members

A group is a member of a share, and every user in the group inherits that role. Adding a user to the group grants them access to every share the group is a member of; removing them revokes it. No per-user membership maintenance.

Groups are typically synchronized from ScaiKey via webhooks — changes in your identity provider propagate automatically.

## Invitations — members who don't exist yet

If you want to add someone who doesn't have a ScaiDrive account yet, use **invitations**:

```bash
curl -X POST $SCAIDRIVE_URL/api/v1/shares/shr_01J3K/invite \
  -H "Authorization: Bearer $SCAIDRIVE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "partner@external.com",
    "role": "reader",
    "message": "Quarterly planning docs",
    "expires_in_days": 14
  }'
```

ScaiDrive generates a unique invitation token, sends an email via ScaiSend, and waits. When the recipient clicks the link, they log in through ScaiKey (creating an account if needed), then accept the invitation:

```bash
curl -X POST $SCAIDRIVE_URL/api/v1/users/me/invitations/inv_01J5N/accept \
  -H "Authorization: Bearer $SCAIDRIVE_TOKEN"
```

At that point the invitation is consumed and a ShareMember record is created.

Pending invitations for the current user:

```bash
curl -H "Authorization: Bearer $SCAIDRIVE_TOKEN" \
     $SCAIDRIVE_URL/api/v1/users/me/invitations
```

Invitations that expire before being accepted transition to `status: expired` and can be revoked.

## Share lifecycle

```mermaid
stateDiagram-v2
  [*] --> Active: POST /shares
  Active --> Trashed: DELETE /shares/{id}
  Trashed --> Active: restore
  Trashed --> [*]: GC after retention<br/>(permanently deleted)
```

Soft-delete is the default. `DELETE /api/v1/shares/{id}` marks the share as `is_deleted: true` but keeps the content. Recovery is possible until the retention period elapses. For permanent deletion, a separate admin endpoint exists (requires tenant admin).

## Quotas per share

Every share can have an optional `quota_bytes`. If set, writes that would push `used_bytes` above the quota fail with `507 QUOTA_EXCEEDED`. If unset, the share inherits the tenant quota minus other consumption.

Quotas can be updated at any time; lowering a quota below current usage doesn't delete content but blocks further writes until usage drops below the new limit.

See [Quotas Reference](/docs/scaidrive/reference/quotas).

## Usage tracking

Every share tracks:

- `used_bytes` — sum of file sizes (current versions only).
- `version_bytes` — space consumed by prior versions.
- `trash_bytes` — space held by soft-deleted items.
- `file_count`, `folder_count`.

These are updated on every write and can be read via `GET /api/v1/users/me/stats` (for the calling user's shares) or `GET /api/v1/quotas/usage/shares/{share_id}` (for any share you can read).

## What's next

- [Permissions and ACLs](/docs/scaidrive/core-concepts/permissions-and-acls) — how per-file access is resolved.
- [Sharing Guide](/docs/scaidrive/api-guides/sharing) — managing members and invitations in practice.
- [Shares Reference](/docs/scaidrive/reference/shares) — all share endpoints.