External sharing

Share a file or folder with one person by email

Changed on

Admin, or the folder's manager for a folder. Only the role is relaxed for a manager: every share needs the external-sharing entitlement (Teams/Enterprise, or the collab.external_sharing feature on self-host; 403 EXTERNAL_SHARING_NOT_ENTITLED) and an email the workspace's allowed domains or emails accept (403 DOMAIN_NOT_ALLOWED). Invites an external user if needed and mints an external_user grant; re-sharing is idempotent and replaces the expiry. For a folder, the invite email's join link carries ?folder=<id> through sign-in and lands on /shared?folder=<id> (that folder's branded portal); an already-active person's email links there too. Returns 409 if the email is already an internal member. With guest: true (folders only) no account is created: a guest grant whose subject is the email itself, and an emailed link that opens the folder in a space-guest session. The guest can also open it from /shared?folder=<id> with an email code. They see that folder's subtree only, up to the capability; revoking or expiring the grant ends their session on the next request.

post/v1/workspaces/{workspaceId}/share-person

Request

  • Base URL
    https://shareout.site
  • URL
    https://shareout.site/v1/workspaces/{workspaceId}/share-person
  • Auth
    HTTP bearer

Request body

emailstring email required
resource_type'file' | 'folder' required
resource_idstring required
capability'view' | 'comment'
expires_in_daysinteger

Access ends this many days from now (UI presets 7/30/90). Wins over expires_at.

expires_atstring

ISO date-time (or YYYY-MM-DD = end of that day, UTC) when access ends. Omit both for no expiry; a re-share replaces the previous expiry.

guestboolean

Folders only. Share as a guest with no account (subject_type guest); the person gets an emailed link instead of an invite.

Response

Grant created (idempotent re-share)

emailstring
guestboolean

Present and true for a guest share.

email_sentboolean

Guest shares only — whether the link email went out.

Changes

    • warning

      added the new guest enum value to the / response property for the response status

    • info

      added the new optional request property

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • breaking

      removed the success response with the status

    • info

      added the non-success response with the status

    • info

      added the success response with the status