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.

Sharing Policies Overview

Method API Path Description

GET

/​api/​sharing_policies

List sharing policies

POST

/​api/​sharing_policies

Create a sharing policy

GET

/​api/​sharing_policies/​{sharing_policy_id}

Get a sharing policy

DELETE

/​api/​sharing_policies/​{sharing_policy_id}

Delete a sharing policy

Details

List sharing policies

GET /api/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

page_size

integer <int>

Maximum page size for a paginated response

marker

string

Pagination marker for a paginated response

username

string

Username to query information about

collection_id (required)

string <uuid>

ID of the collection

Responses

200 - List sharing policies response
Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Version 1.1.0 adds optional authorization_parameters to help process authorization or authentication errors

One of the following schemas:

​

{
  "code": "string",
  "data": [
    {
      "DATA_TYPE": "sharing_policy#1.0.0",
      "collection_id": "4bdef85c-3f50-4006-a713-2350da665f80",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "sharing_restrict_paths": {
        "DATA_TYPE": "path_restrictions#1.0.0",
        "none": [
          "string"
        ],
        "read": [
          "string"
        ],
        "read_write": [
          "string"
        ]
      },
      "users": [
        "string"
      ]
    }
  ],
  "DATA_TYPE": "result#1.0.0",
  "detail": null,
  "has_next_page": false,
  "http_response_code": 100,
  "marker": "string",
  "message": "string"
}
400 - Bad Request
403 - Permission denied
Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Version 1.1.0 adds optional authorization_parameters to help process authorization or authentication errors

One of the following schemas:

​

{
  "code": "string",
  "http_response_code": 100,
  "detail": null,
  "DATA_TYPE": "result#1.0.0",
  "data": [
    {}
  ],
  "has_next_page": false,
  "marker": "string",
  "message": "string"
}

Create a sharing policy

POST /api/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

Content-Type: 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 sharing_policy#1.0.0

Type of this document

collection_id

string <uuid>

Id of the mapped collection which this policy is associated with

id

string <uuid>

Unique id for this sharing policy

sharing_restrict_paths

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 of 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",
  "collection_id": "4bdef85c-3f50-4006-a713-2350da665f80",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "sharing_restrict_paths": {
    "DATA_TYPE": "path_restrictions#1.0.0",
    "none": [
      "string"
    ],
    "read": [
      "string"
    ],
    "read_write": [
      "string"
    ]
  },
  "users": [
    "string"
  ]
}

Responses

201 - List sharing policies response
Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Version 1.1.0 adds optional authorization_parameters to help process authorization or authentication errors

One of the following schemas:

​

{
  "code": "string",
  "data": [
    {
      "DATA_TYPE": "sharing_policy#1.0.0",
      "collection_id": "4bdef85c-3f50-4006-a713-2350da665f80",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "sharing_restrict_paths": {
        "DATA_TYPE": "path_restrictions#1.0.0",
        "none": [
          "string"
        ],
        "read": [
          "string"
        ],
        "read_write": [
          "string"
        ]
      },
      "users": [
        "string"
      ]
    }
  ],
  "DATA_TYPE": "result#1.0.0",
  "detail": null,
  "has_next_page": false,
  "http_response_code": 100,
  "marker": "string",
  "message": "string"
}
400 - Bad Request
403 - Permission denied
Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Version 1.1.0 adds optional authorization_parameters to help process authorization or authentication errors

One of the following schemas:

​

{
  "code": "string",
  "http_response_code": 100,
  "detail": null,
  "DATA_TYPE": "result#1.0.0",
  "data": [
    {}
  ],
  "has_next_page": false,
  "marker": "string",
  "message": "string"
}
415 - Unsupported media type
422 - Unprocessable entity

Details

Get a sharing policy

GET /api/sharing_policies/{sharing_policy_id}

Get a sharing policy.

Authorization

  • RoleAuthorizer:

    • endpoint:owner

    • endpoint:administrator

    • collection:administrator:{collection_id}

Path parameters

▷ sharing_policy_id

Id of the sharing policy

Parameter Type Description

sharing_policy_id (required)

string <uuid>

Id of the sharing policy

Responses

200 - Get sharing policy response
Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Version 1.1.0 adds optional authorization_parameters to help process authorization or authentication errors

One of the following schemas:

​

{
  "code": "string",
  "data": [
    {
      "DATA_TYPE": "sharing_policy#1.0.0",
      "collection_id": "4bdef85c-3f50-4006-a713-2350da665f80",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "sharing_restrict_paths": {
        "DATA_TYPE": "path_restrictions#1.0.0",
        "none": [
          "string"
        ],
        "read": [
          "string"
        ],
        "read_write": [
          "string"
        ]
      },
      "users": [
        "string"
      ]
    }
  ],
  "DATA_TYPE": "result#1.0.0",
  "detail": null,
  "has_next_page": false,
  "http_response_code": 100,
  "marker": "string",
  "message": "string"
}
403 - Permission denied
Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Version 1.1.0 adds optional authorization_parameters to help process authorization or authentication errors

One of the following schemas:

​

{
  "code": "string",
  "http_response_code": 100,
  "detail": null,
  "DATA_TYPE": "result#1.0.0",
  "data": [
    {}
  ],
  "has_next_page": false,
  "marker": "string",
  "message": "string"
}
404 - Not found

Delete a sharing policy

DELETE /api/sharing_policies/{sharing_policy_id}

Delete a sharing policy.

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}

Path parameters

▷ sharing_policy_id

Id of the sharing policy

Parameter Type Description

sharing_policy_id (required)

string <uuid>

Id of the sharing policy

Responses

200 - Delete sharing policy response
Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Version 1.1.0 adds optional authorization_parameters to help process authorization or authentication errors

One of the following schemas:

​

{
  "DATA_TYPE": "result#1.0.0",
  "code": "string",
  "data": [
    {}
  ],
  "detail": null,
  "has_next_page": false,
  "http_response_code": 100,
  "marker": "string",
  "message": "string"
}
403 - Permission denied
Content-Type: application/json

This is the result envelope returned from all operations in this API. Each operation may add properties to this base document type with additional operation-specific data values.

Version 1.1.0 adds optional authorization_parameters to help process authorization or authentication errors

One of the following schemas:

​

{
  "code": "string",
  "http_response_code": 100,
  "detail": null,
  "DATA_TYPE": "result#1.0.0",
  "data": [
    {}
  ],
  "has_next_page": false,
  "marker": "string",
  "message": "string"
}
404 - Not found