Shares and Ownership

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:

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:

1
2
3
4

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:

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.

Members are added via the members API:

1
2
3
4
5
6
7
8

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:

1
2
3
4
5
6
7
8
9

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:

1
2

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:

1
2

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#

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.

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 — how per-file access is resolved.
• Sharing Guide — managing members and invitations in practice.
• Shares Reference — all share endpoints.