Grant access to a user or group
const url = 'https://work.optidata.cloud/api/drives/1/nodes/300754/share/permission';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"user_id":15,"actions":"view"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://work.optidata.cloud/api/drives/1/nodes/300754/share/permission \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "user_id": 15, "actions": "view" }'Grants actions on the node to a user or a group. Send exactly one of
user_id or group_id; sending neither is rejected. Granting again to
the same target updates the existing grant rather than duplicating it.
The share is created on the fly if the node was not shared yet.
Requires permission to share the node.
Authorizations
Section titled “Authorizations”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters”Numeric id of the drive. Read it from GET /drives/config.json.
Numeric id of the node (file or folder).
Request Bodyrequired
Section titled “Request Bodyrequired”object
Grant to this user. Mutually exclusive with group_id.
Grant to this group. Mutually exclusive with user_id.
Permission level to grant.
Examples
{ "user_id": 15, "actions": "view"}Responses
Section titled “ Responses ”The node, its share and the resulting permission.
object
A file or a folder. type is 1 for a folder and 2 for a file; the
booleans is_folder / is_file are derived from it. Content attributes
(content_*) are null on folders and on files that have no bytes yet.
object
Parent folder id. null marks a company folder (top level).
Owner of the node.
1 = folder, 2 = file.
Whether the file can be co-edited in the online editor.
Whether the node lives in cold storage. Present only on detail reads.
true when this node was the explicit target of a delete; null when it
was removed only because an ancestor was deleted.
Materialised ancestor path, dot separated ids.
Current content version of the file.
One stored version of a file’s bytes.
object
Opaque storage path of this content version.
SHA-256 of this version, the value a caller sends back as base_content_hash.
The hash_sha256 of the version this one was written from, as sent
in base_content_hash and accepted by the server. null when the
write carried no base. Equal to the hash a sync client last
committed: the other side edited that version. Different, or
null: the client cannot tell, and should keep a conflict copy.
The caller’s effective permission level on this node. Present on listings derived from shares.
A user of the tenant.
object
Identifier of the company (tenant) the user belongs to.
Role of the user inside the tenant.
Profile extras (avatar, job title). Loaded only where noted.
Groups the user belongs to. Loaded only where noted.
A group of users inside the tenant.
object
Tenant-wide identifier of the group; used in paths.
Members of the group, each with its embedded user.
object
Presence status of the user. Loaded only where noted.
Rendered presence details (type, icon, message). Present on dashboard listings.
Per-node presentation settings (colour, shared flag).
A per-user flag on a node.
object
Kind of marker.
object
An advisory lock held on a file while it is being edited. Take one before replacing the content of a file another user could be working on.
object
Free-text reason shown to other users.
Free-text label naming the client that took the lock.
Opaque per-installation identifier of the lock holder.
A user of the tenant.
object
Identifier of the company (tenant) the user belongs to.
Role of the user inside the tenant.
Profile extras (avatar, job title). Loaded only where noted.
Groups the user belongs to. Loaded only where noted.
A group of users inside the tenant.
object
Tenant-wide identifier of the group; used in paths.
Members of the group, each with its embedded user.
object
Presence status of the user. Loaded only where noted.
Rendered presence details (type, icon, message). Present on dashboard listings.
An advisory lock held on a file while it is being edited. Take one before replacing the content of a file another user could be working on.
object
Free-text reason shown to other users.
Free-text label naming the client that took the lock.
Opaque per-installation identifier of the lock holder.
A user of the tenant.
object
Identifier of the company (tenant) the user belongs to.
Role of the user inside the tenant.
Profile extras (avatar, job title). Loaded only where noted.
Groups the user belongs to. Loaded only where noted.
A group of users inside the tenant.
object
Tenant-wide identifier of the group; used in paths.
Members of the group, each with its embedded user.
object
Presence status of the user. Loaded only where noted.
Rendered presence details (type, icon, message). Present on dashboard listings.
Non-null while the node is in the trash.
The sharing record of a node, holding every permission granted on it.
object
Owner of the share.
Set once a public link is enabled for the share.
One grant inside a share. Exactly one of user_id or group_id is set;
the link permission has both null.
object
Permission level granted. share and owner are legacy aliases of manage.
Lifetime of a link permission in seconds; -1 means never expires.
One grant inside a share. Exactly one of user_id or group_id is set;
the link permission has both null.
object
Permission level granted. share and owner are legacy aliases of manage.
Lifetime of a link permission in seconds; -1 means never expires.
A user of the tenant.
object
Identifier of the company (tenant) the user belongs to.
Role of the user inside the tenant.
Profile extras (avatar, job title). Loaded only where noted.
Groups the user belongs to. Loaded only where noted.
A group of users inside the tenant.
object
Tenant-wide identifier of the group; used in paths.
Members of the group, each with its embedded user.
object
Presence status of the user. Loaded only where noted.
Rendered presence details (type, icon, message). Present on dashboard listings.
A group of users inside the tenant.
object
Tenant-wide identifier of the group; used in paths.
Members of the group, each with its embedded user.
object
A file or a folder. type is 1 for a folder and 2 for a file; the
booleans is_folder / is_file are derived from it. Content attributes
(content_*) are null on folders and on files that have no bytes yet.
object
Parent folder id. null marks a company folder (top level).
Owner of the node.
1 = folder, 2 = file.
Whether the file can be co-edited in the online editor.
Whether the node lives in cold storage. Present only on detail reads.
true when this node was the explicit target of a delete; null when it
was removed only because an ancestor was deleted.
Materialised ancestor path, dot separated ids.
Current content version of the file.
One stored version of a file’s bytes.
object
Opaque storage path of this content version.
SHA-256 of this version, the value a caller sends back as base_content_hash.
The hash_sha256 of the version this one was written from, as sent
in base_content_hash and accepted by the server. null when the
write carried no base. Equal to the hash a sync client last
committed: the other side edited that version. Different, or
null: the client cannot tell, and should keep a conflict copy.
The caller’s effective permission level on this node. Present on listings derived from shares.
A user of the tenant.
object
Identifier of the company (tenant) the user belongs to.
Role of the user inside the tenant.
Profile extras (avatar, job title). Loaded only where noted.
Groups the user belongs to. Loaded only where noted.
A group of users inside the tenant.
object
Tenant-wide identifier of the group; used in paths.
Members of the group, each with its embedded user.
object
Presence status of the user. Loaded only where noted.
Rendered presence details (type, icon, message). Present on dashboard listings.
Per-node presentation settings (colour, shared flag).
A per-user flag on a node.
object
Kind of marker.
object
An advisory lock held on a file while it is being edited. Take one before replacing the content of a file another user could be working on.
object
Free-text reason shown to other users.
Free-text label naming the client that took the lock.
Opaque per-installation identifier of the lock holder.
A user of the tenant.
object
Identifier of the company (tenant) the user belongs to.
Role of the user inside the tenant.
Profile extras (avatar, job title). Loaded only where noted.
Groups the user belongs to. Loaded only where noted.
A group of users inside the tenant.
object
Tenant-wide identifier of the group; used in paths.
Members of the group, each with its embedded user.
object
Presence status of the user. Loaded only where noted.
Rendered presence details (type, icon, message). Present on dashboard listings.
An advisory lock held on a file while it is being edited. Take one before replacing the content of a file another user could be working on.
object
Free-text reason shown to other users.
Free-text label naming the client that took the lock.
Opaque per-installation identifier of the lock holder.
A user of the tenant.
object
Identifier of the company (tenant) the user belongs to.
Role of the user inside the tenant.
Profile extras (avatar, job title). Loaded only where noted.
Groups the user belongs to. Loaded only where noted.
A group of users inside the tenant.
object
Tenant-wide identifier of the group; used in paths.
Members of the group, each with its embedded user.
object
Presence status of the user. Loaded only where noted.
Rendered presence details (type, icon, message). Present on dashboard listings.
Non-null while the node is in the trash.
One grant inside a share. Exactly one of user_id or group_id is set;
the link permission has both null.
object
Permission level granted. share and owner are legacy aliases of manage.
Lifetime of a link permission in seconds; -1 means never expires.
Example
{ "node": { "id": 300754, "drive_id": 1, "type": 1, "name": "Contracts", "ltree_path": "300754.665198", "content_mime_type": "application/pdf", "content_size_bytes": 148213, "content": { "id": 613488, "mime_type": "application/pdf", "size_bytes": 148213 }, "actions": "none", "user": { "id": 15, "uuid": "9c1f0e2a-4d31-4d8a-8c1a-1f0b6b1f9a10", "cuid": "a1b2c3d4-2226-46c1-91b2-a9e9ba4c2d5b", "username": "jane.doe@acme.example", "email": "jane.doe@acme.example", "name": "Jane Doe", "full_name": "Jane Doe", "company_name": "Acme", "role": "super-admin", "status": "active", "groups": [ { "id": 560, "guid": "a19d5670-335d-4285-8ee4-fcb54cb70faf", "name": "Finance" } ] }, "markers": [ { "type": "favorite" } ], "lock": { "user": { "id": 15, "uuid": "9c1f0e2a-4d31-4d8a-8c1a-1f0b6b1f9a10", "cuid": "a1b2c3d4-2226-46c1-91b2-a9e9ba4c2d5b", "username": "jane.doe@acme.example", "email": "jane.doe@acme.example", "name": "Jane Doe", "full_name": "Jane Doe", "company_name": "Acme", "role": "super-admin", "status": "active", "groups": [ { "id": 560, "guid": "a19d5670-335d-4285-8ee4-fcb54cb70faf", "name": "Finance" } ] } }, "locks": [ { "user": { "id": 15, "uuid": "9c1f0e2a-4d31-4d8a-8c1a-1f0b6b1f9a10", "cuid": "a1b2c3d4-2226-46c1-91b2-a9e9ba4c2d5b", "username": "jane.doe@acme.example", "email": "jane.doe@acme.example", "name": "Jane Doe", "full_name": "Jane Doe", "company_name": "Acme", "role": "super-admin", "status": "active", "groups": [ { "id": 560, "guid": "a19d5670-335d-4285-8ee4-fcb54cb70faf", "name": "Finance" } ] } } ] }, "share": { "id": 2743, "node_type": 1, "permissions": [ { "actions": "none" } ], "link_share_permission": { "actions": "none" }, "users": [ { "id": 15, "uuid": "9c1f0e2a-4d31-4d8a-8c1a-1f0b6b1f9a10", "cuid": "a1b2c3d4-2226-46c1-91b2-a9e9ba4c2d5b", "username": "jane.doe@acme.example", "email": "jane.doe@acme.example", "name": "Jane Doe", "full_name": "Jane Doe", "company_name": "Acme", "role": "super-admin", "status": "active", "groups": [ { "id": 560, "guid": "a19d5670-335d-4285-8ee4-fcb54cb70faf", "name": "Finance" } ] } ], "groups": [ { "id": 560, "guid": "a19d5670-335d-4285-8ee4-fcb54cb70faf", "name": "Finance" } ], "node": { "id": 300754, "drive_id": 1, "type": 1, "name": "Contracts", "ltree_path": "300754.665198", "content_mime_type": "application/pdf", "content_size_bytes": 148213, "content": { "id": 613488, "mime_type": "application/pdf", "size_bytes": 148213 }, "actions": "none", "user": { "id": 15, "uuid": "9c1f0e2a-4d31-4d8a-8c1a-1f0b6b1f9a10", "cuid": "a1b2c3d4-2226-46c1-91b2-a9e9ba4c2d5b", "username": "jane.doe@acme.example", "email": "jane.doe@acme.example", "name": "Jane Doe", "full_name": "Jane Doe", "company_name": "Acme", "role": "super-admin", "status": "active", "groups": [ { "id": 560, "guid": "a19d5670-335d-4285-8ee4-fcb54cb70faf", "name": "Finance" } ] }, "markers": [ { "type": "favorite" } ], "lock": { "user": { "id": 15, "uuid": "9c1f0e2a-4d31-4d8a-8c1a-1f0b6b1f9a10", "cuid": "a1b2c3d4-2226-46c1-91b2-a9e9ba4c2d5b", "username": "jane.doe@acme.example", "email": "jane.doe@acme.example", "name": "Jane Doe", "full_name": "Jane Doe", "company_name": "Acme", "role": "super-admin", "status": "active", "groups": [ { "id": 560, "guid": "a19d5670-335d-4285-8ee4-fcb54cb70faf", "name": "Finance" } ] } }, "locks": [ { "user": { "id": 15, "uuid": "9c1f0e2a-4d31-4d8a-8c1a-1f0b6b1f9a10", "cuid": "a1b2c3d4-2226-46c1-91b2-a9e9ba4c2d5b", "username": "jane.doe@acme.example", "email": "jane.doe@acme.example", "name": "Jane Doe", "full_name": "Jane Doe", "company_name": "Acme", "role": "super-admin", "status": "active", "groups": [ { "id": 560, "guid": "a19d5670-335d-4285-8ee4-fcb54cb70faf", "name": "Finance" } ] } } ] } }, "permission": { "actions": "none" }}Missing, malformed or expired authentication key.
Authentication failures use an error key rather than message.
object
Examples
No bearer token sent
{ "error": "JWT passport exception: Missing bearer token in request"}The caller may not share the node, the node belongs to another drive,
or neither user_id nor group_id was sent.
Authentication failures use an error key rather than message.
object
Examples
{ "error": "Invalid permission: either user or group must be set"}The resource does not exist, or does not belong to the given drive.
Generic error envelope used by policy, binding and framework failures.
object
Human-readable description of the failure.
Examples
{ "message": "No query results for model [App\\Models\\Node] 99999999"}The request body or query string failed validation.
object
The first validation message.
Validation messages keyed by field name.
object
Examples
{ "message": "The name field is required.", "errors": { "name": [ "The name field is required." ] }}Rate limit exceeded. Retry after the window resets.
Generic error envelope used by policy, binding and framework failures.
object
Human-readable description of the failure.
Examples
{ "message": "Too Many Attempts."}