Sharing Policies
Sharing Policies
The Sharing Restrictions management API allows endpoint owners, endpoint administrators and collection administrators to manage sharing policies that contain information about both which users can share data and which paths in the connector’s virtual filesystem they may share. These restrictions can only be created on a mapped collection, but are enforced on guest collection creation and access.
Details
Create a Sharing Policy
POST /sharing_policies
Create a new sharing policy document for a mapped collection. This new document will be added to the set of sharing policy documents for this collection. The sharing policy documents which either have no user constraint, or match the guest collection owner are used to determine which paths are available to be shared.
This returns the policy document with the "id" field populated with the assigned ID of this policy.
Authorization
-
RoleAuthorizer: [ endpoint:owner, endpoint:administrator, collection:administrator:{collection_id} ]
Request body
application/json
Sharing policies for a mapped collection. This document type allows endpoint and collection administrators to optionally constrain sharing path policies for particular users. The sharing_restrict_paths property has a similar meaning to that of the sharing_restrict_paths in the collection document; however, it is in effect only for specific users.
If the users property is null, then the restriction applies to all users. If it is non-null, then this restriction applies only to accounts which have been mapped to the enumerated storage gateway user accounts.
Multiple sharing policies can be defined for a mapped collection. When a guest collection is created or accessed, only the policies relevant to the user which created the account are enforced.
Name |
Type |
Description |
DATA_TYPE |
string |
Type of this document |
id |
string <uuid> |
ID for this sharing policy |
collection_id |
string <uuid> |
ID of the mapped collection which this policy is associated with. |
sharing_restrict_paths |
One of { object PathRestrictions } |
Restrictions on which paths may be shared in guest collections related to this mapped collection. These paths are relative to the root_path property of the mapped collection. |
users |
array (string) |
List of local user accounts that this policy applies to. If omitted or null, this restriction applies to all local user accounts. |
Example
{
"DATA_TYPE": "sharing_policy#1.0.0",
"id": "97d6ec0b-a3c2-4723-a1a0-285b2b8f015a",
"collection_id": "14326300-5a33-4387-9bb0-7f85c3dc3185",
"sharing_restrict_paths": {
"DATA_TYPE": "path_restrictions#1.0.0",
"read": [
"/public"
],
"read_write": [
"/home",
"/projects"
],
"none": [
"/private"
]
},
"users": [
"username"
]
}
Responses
200 - Sharing Policy Response
Name |
Type |
Description |
code |
string |
|
data |
array (object) ( link:Sharing Policies] ) |
|
DATA_TYPE |
string |
Type of this document. |
http_response_code |
integer |
Numeric HTTP response code |
detail |
Machine readable response details |
|
message |
string |
Message describing this result. |
has_next_page |
boolean |
Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation. |
marker |
string |
Opaque marker that may be passed to this API call to
fetch the next page of results if the returned document
has |
{
"code": "success",
"data": [
{
"DATA_TYPE": "sharing_policy#1.0.0",
"id": "97d6ec0b-a3c2-4723-a1a0-285b2b8f015a",
"collection_id": "14326300-5a33-4387-9bb0-7f85c3dc3185",
"sharing_restrict_paths": {
"DATA_TYPE": "path_restrictions#1.0.0",
"read": [
"/public"
],
"read_write": [
"/home",
"/projects"
],
"none": [
"/private"
]
},
"users": [
"username"
]
}
],
"DATA_TYPE": "result#1.0.0",
"http_response_code": 200,
"detail": null,
"message": "Operation successful",
"has_next_page": false,
"marker": "string"
}
List Sharing Policies
GET /sharing_policies
List the sharing policies for a mapped collection.
This may return a paginated result; the marker
and page_size
query parameters can be used to obtain the next page of
response data for the query.
If the username
query parameter is passed to this function then
only the policies which are relevant to the given username are
returned. This will include policies where the users property
is null
or contains the given username.
Authorization
-
RoleAuthorizer: [ endpoint:owner, endpoint:administrator, collection:administrator:{collection_id} ]
Query Parameters
Parameter | Type | Description |
---|---|---|
collection_id (required) |
string Any |
ID of the Collection |
username |
string Any |
Username to query information about. |
marker |
string Any |
Pagination marker for a paginated response |
page_size |
integer Any |
Maximum page size for a paginated response |
Responses
200 - Get Sharing Restrict Paths Response
Name |
Type |
Description |
code |
string |
|
data |
array (object) ( link:Sharing Policies] ) |
|
DATA_TYPE |
string |
Type of this document. |
http_response_code |
integer |
Numeric HTTP response code |
detail |
Machine readable response details |
|
message |
string |
Message describing this result. |
has_next_page |
boolean |
Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation. |
marker |
string |
Opaque marker that may be passed to this API call to
fetch the next page of results if the returned document
has |
{
"code": "success",
"data": [
{
"DATA_TYPE": "sharing_policy#1.0.0",
"id": "97d6ec0b-a3c2-4723-a1a0-285b2b8f015a",
"collection_id": "14326300-5a33-4387-9bb0-7f85c3dc3185",
"sharing_restrict_paths": {
"DATA_TYPE": "path_restrictions#1.0.0",
"read": [
"/public"
],
"read_write": [
"/home",
"/projects"
],
"none": [
"/private"
]
},
"users": [
"username"
]
}
],
"DATA_TYPE": "result#1.0.0",
"http_response_code": 200,
"detail": null,
"message": "Operation successful",
"has_next_page": false,
"marker": "string"
}
Details
Get a Sharing Policy
GET /sharing_policies/{sharing_policy_id}
Get a sharing policy document by its ID.
Authorization
-
RoleAuthorizer: [ endpoint:owner, endpoint:administrator, collection:administrator:{collection_id} ]
Responses
200 - Get Sharing Policies Response
Name |
Type |
Description |
code |
string |
|
data |
array (object) ( link:Sharing Policies] ) |
|
DATA_TYPE |
string |
Type of this document. |
http_response_code |
integer |
Numeric HTTP response code |
detail |
Machine readable response details |
|
message |
string |
Message describing this result. |
has_next_page |
boolean |
Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation. |
marker |
string |
Opaque marker that may be passed to this API call to
fetch the next page of results if the returned document
has |
{
"code": "success",
"data": [
{
"DATA_TYPE": "sharing_policy#1.0.0",
"id": "97d6ec0b-a3c2-4723-a1a0-285b2b8f015a",
"collection_id": "14326300-5a33-4387-9bb0-7f85c3dc3185",
"sharing_restrict_paths": {
"DATA_TYPE": "path_restrictions#1.0.0",
"read": [
"/public"
],
"read_write": [
"/home",
"/projects"
],
"none": [
"/private"
]
},
"users": [
"username"
]
}
],
"DATA_TYPE": "result#1.0.0",
"http_response_code": 200,
"detail": null,
"message": "Operation successful",
"has_next_page": false,
"marker": "string"
}
Delete a sharing policy
DELETE /sharing_policies/{sharing_policy_id}
Delete the SharingPolicy document with the given ID. This may alter the behavior of existing guest collections, if the policies change the visible parts of the storage gateway’s virtual file system for the guest collection creator.
Authorization
-
RoleAuthorizer: [ endpoint:owner, endpoint:administrator, collection:administrator:{collection_id} ]
Responses
200 - Delete SharingPolicy Response
Name |
Type |
Description |
code |
string |
|
DATA_TYPE |
string |
Type of this document. |
http_response_code |
integer |
Numeric HTTP response code |
detail |
Machine readable response details |
|
message |
string |
Message describing this result. |
data |
array (object) |
|
has_next_page |
boolean |
Boolean flag indicating whether or not additional pages of response data may be requested by passing the marker to the same operation. |
marker |
string |
Opaque marker that may be passed to this API call to
fetch the next page of results if the returned document
has |
{
"code": "success",
"DATA_TYPE": "result#1.0.0",
"http_response_code": 200,
"detail": null,
"message": "Operation successful",
"data": [
{}
],
"has_next_page": false,
"marker": "string"
}