doc/api/share.md
Share endpoints allow sharing files with other users.
/share (auth required)The /share endpoint shares 1 or more filesystem items
with one or more recipients. The recipients will receive
some notification about the shared item, making this
different from calling /grant-user-user with a permission.
When users are specified by email they will receive a share link.
Each item specified in the shares property is a tag-typed
object of type fs-share or app-share.
fs-share)File shares grant permission to a file or directory. By default
this is read permission. If access is specified as "write",
then write permission will be granted.
app-share)App shares grant permission to read a protected app.
If there is a subdomain associated with the app, and the owner
of the subdomain is the same as the owner of the app, then
permission to access the subdomain will be granted.
Note that the subdomain is only associated if the subdomain
entry has associated_app_id set according to the app's id,
and will not be considered "associated" if only the index_url
happens to match the subdomain url.
If the app has shared_appdata set to true in its metadata
object, the recipient of the share will also get write permission
to the app owner's corresponding appdata directory. The appdata
directory must exist for this to work as expected
(otherwise the permission rewrite rule fails since the uuid
can't be determined).
{
"recipients": [
"user_that_gets_shared_to",
"[email protected]"
],
"shares": [
{
"$": "app-share",
"name": "some-app-name"
},
{
"$": "app-share",
"uid": "app-SOME-APP-UID"
},
{
"$": "fs-share",
"path": "/some/file/or/directory"
},
{
"$": "fs-share",
"path": "SOME-FILE-UUID"
}
]
}
string | Array<string>string: email or usernameobject | Array<object>
boolapi:sharev0.0.0"success", "mixed", "aborted"api:status-report or
heyputer:api/APIErrorapi:status-report or
heyputer:api/APIErrortrue if presentawait fetch("http://puter.localhost:4100/share", {
headers: {
"Content-Type": "application/json",
"Authorization": `Bearer ${puter.authToken}`,
},
body: JSON.stringify({
recipients: [
"user_that_gets_shared_to",
"[email protected]"
],
shares: [
{
$: "app-share",
name: "some-app-name"
},
{
$: "app-share",
uid: "app-SOME-APP-UID"
},
{
$: "fs-share",
path: "/some/file/or/directory"
},
{
$: "fs-share",
path: "SOME-FILE-UUID"
}
]
}),
method: "POST",
});
{
"$": "api:share",
"$version": "v0.0.0",
"status": "success",
"recipients": [
{
"$": "api:status-report",
"status": "success"
}
],
"paths": [
{
"$": "api:status-report",
"status": "success"
}
],
"dry_run": true
}
{
"$": "api:share",
"$version": "v0.0.0",
"status": "mixed",
"recipients": [
{
"$": "api:status-report",
"status": "success"
}
],
"paths": [
{
"$": "heyputer:api/APIError",
"code": "subject_does_not_exist",
"message": "File or directory not found.",
"status": 404
}
],
"dry_run": true
}
{
"$": "api:share",
"$version": "v0.0.0",
"status": "mixed",
"recipients": [
{
"$": "heyputer:api/APIError",
"code": "user_does_not_exist",
"message": "The user `non_existing_user` does not exist.",
"username": "non_existing_user",
"status": 422
}
],
"paths": [
{
"$": "api:status-report",
"status": "success"
}
],
"dry_run": true
}
/sharelink/check (no auth)The /sharelink/check endpoint verifies that a token provided
by a share link is valid.
await fetch(`${config.api_origin}/sharelink/check`, {
"headers": {
"Content-Type": "application/json",
"Authorization": `Bearer ${puter.authToken}`,
},
"body": JSON.stringify({
token: '...',
}),
"method": "POST",
});
string
The token from the querystring parameterA type-tagged object, either of type api:share or api:error
{
"$": "api:share",
"uid": "836671d4-ac5d-4bd3-bc0a-ec357e0d8f02",
"email": "[email protected]"
}
{
"$": "api:error",
"message":"Field `token` is required.",
"key":"token",
"code":"field_missing"
}
/sharelink/apply (no auth)The /sharelink/apply endpoint applies a share to the current
user if and only if that user's email is confirmed and matches
the email associated with the share.
await fetch(`${config.api_origin}/sharelink/apply`, {
"headers": {
"Content-Type": "application/json",
"Authorization": `Bearer ${puter.authToken}`,
},
"body": JSON.stringify({
uid: '836671d4-ac5d-4bd3-bc0a-ec357e0d8f02',
}),
"method": "POST",
});
string
The uid of an existing share, received using /sharelink/checkA type-tagged object, either of type api:status-report or api:error
{"$":"api:status-report","status":"success"}
{
"message": "This share can not be applied to this user.",
"code": "can_not_apply_to_this_user"
}
/sharelink/request (no auth)The /sharelink/request endpoint requests the permissions associated
with a share link to the issuer of the share (user that sent the share).
This can be used when a user is logged in, but that user's email does
not match the email associated with the share.
await fetch(`${config.api_origin}/sharelink/request`, {
"headers": {
"Content-Type": "application/json",
"Authorization": `Bearer ${puter.authToken}`,
},
"body": JSON.stringify({
uid: '836671d4-ac5d-4bd3-bc0a-ec357e0d8f02',
}),
"method": "POST",
});
string
The uid of an existing share, received using /sharelink/checkA type-tagged object, either of type api:status-report or api:error
{"$":"api:status-report","status":"success"}
{
"message": "This share is already valid for this user; POST to /apply for access",
"code": "no_need_to_request"
}