Permissions - Huddle/huddle-apis GitHub Wiki

Summary

Permissions describe which actions apply to a workspace, folder, or (via the parent folder) a document. These resources are served by the Files API; public URLs use the /files/ prefix.

Operations

Method Path Purpose Details
GET /files/workspaces/54321/permissions Retrieve workspace permissions Jump
GET /files/folders/123/permissions Retrieve folder permissions Jump
POST /files/folders/123/permissions Update folder permissions Jump

Retrieving workspace permissions

When retrieving a workspace, the representation may include a link to the permissions resource for that workspace.

Supported HTTP headers

Header More information
If-Modified-Since RFC 2616 §14.25

Example

Request

GET /files/workspaces/54321/permissions HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty
If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT

Response

Uses standard error handling and response headers.

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+xml
Last-Modified: Tue, 1 Feb 2011 13:18:42 GMT

The XML root element is permissionSet (see folder example for shape). Workspace responses do not include per-team permissions on the folder in the same way as folder permissions; see the property table below.

Retrieving folder permissions

When retrieving a folder or retrieving a document, the response can include a link to the folder permissions resource (for documents, this is the parent folder permissions URI).

Two synthetic teams appear in the payload: Workspace Managers and Default Permissions. The former aggregates workspace managers; the latter defines default rights for new teams.

Supported HTTP headers

Header More information
If-Modified-Since RFC 2616 §14.25

Example

Get permissions for folder 123.

Request

GET /files/folders/123/permissions HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty
If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+xml
Last-Modified: Tue, 1 Feb 2011 13:18:42 GMT
<permissionSet>
  <link rel="self" href="https://api.example.com/files/folders/123/permissions" />
  <teams>
    <team title="Default Permissions" type="default">
      <link rel="self" href="https://api.example.com/teams/-1" />
      <permissions>
        <permission type="Read" />
      </permissions>
      <parentPermissions>
        <permission type="Read" />
      </parentPermissions>
      <members />
    </team>
    <team title="team with no permissions" type="members">
      <link rel="self" href="https://api.example.com/teams/111" />
      <permissions />
      <parentPermissions />
      <members>
        <actor name="Barry Potter" email="[email protected]" rel="member">
          <link rel="self" href="https://api.example.com/users/1" />
          <link rel="avatar" href="https://api.example.com/files/users/1/avatar?h=..." type="image/jpeg" />
          <link rel="alternate" href="https://my.huddle.example/user/barry" type="text/html" />
        </actor>
      </members>
    </team>
    <team title="Workspace Managers" type="managers">
      <link rel="self" href="https://api.example.com/workspaces/54321/managers" />
      <permissions>
        <permission type="Edit" />
      </permissions>
      <parentPermissions>
        <permission type="Read" />
        <permission type="Edit" />
      </parentPermissions>
      <members>
        <actor name="Barry Potter" email="[email protected]" rel="manager">
          <link rel="self" href="https://api.example.com/users/1" />
          <link rel="avatar" href="https://api.example.com/files/users/1/avatar?h=..." type="image/jpeg" />
          <link rel="alternate" href="https://my.huddle.example/user/barry" type="text/html" />
        </actor>
      </members>
    </team>
  </teams>
</permissionSet>

Properties

Name Description
teams Teams in the workspace, plus the default team and workspace managers team
members Actors in that team
permissions Permission types for the team on this resource (may be empty). For Folder permissions this reflects folder rights; for Workspace permissions the shape can differ (see live responses for your account).
parentPermissions Parent folder permissions when retrieving non-root folder permissions and the team has some rights on the parent; omitted for workspace permissions, root folder, or when the team has no parent rights

Link relations

Name Description Methods
self This permissions resource GET, POST (POST only for folder updates)

Schema (informal)

start |= permissionSet

permissionSet = element permissionSet {
  ( link+ | ( link+, element teams { team* } ) )
}

Updating folder permissions

To change folder permissions, POST to the folder permissions resource. Besides Read and Edit, accounts with restricted view can use Restricted.

Use the cascade attribute on each permissionChange: true applies the change to subfolders as well; false limits it to the current folder.

Updates are asynchronous: the API returns 202 Accepted and a progress link. Poll that URI until completion, then follow results when present.

Omitted permission types are removed for that team. To clear a team’s permissions on a folder, send an empty permissions element. When removing access, you must cascade to subfolders or the API may respond with 409 Conflict.

Do not include the Workspace Managers team in the payload. The Default Permissions team may be updated like other teams.

Example

Request

POST /files/folders/123/permissions HTTP/1.1
Accept: application/vnd.huddle.data+xml
Content-Type: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty
<permissionChanges>
  <link rel="self" href="https://api.example.com/files/folders/123/permissions" />
  <permissionChange cascade="false">
    <team title="teamA" type="members">
      <link rel="self" href="https://api.example.com/teams/12345" />
      <permissions>
        <permission type="Read" />
        <permission type="Edit" />
      </permissions>
    </team>
  </permissionChange>
  <permissionChange cascade="true">
    <team title="teamB" type="members">
      <link rel="self" href="https://api.example.com/teams/22345" />
      <permissions />
    </team>
  </permissionChange>
  <permissionChange cascade="true">
    <team title="teamC" type="members">
      <link rel="self" href="https://api.example.com/teams/22345" />
      <permissions>
        <permission type="Restricted" />
      </permissions>
    </team>
  </permissionChange>
</permissionChanges>

Response

HTTP/1.1 202 Accepted
Content-Type: application/vnd.huddle.data+xml
<permissionsUpdate>
  <link rel="self" href="https://api.example.com/files/folders/123/permissions" />
  <link rel="progress" href="https://api.example.com/files/bulkprocess/folderpermissions/7b512a88-89a6-45f6-b81b-324e8bcfa4c3" />
</permissionsUpdate>

Link relations (202 body)

Name Description Methods
self Folder permissions resource GET, POST
progress Poll for operation status GET

See also

⚠️ **GitHub.com Fallback** ⚠️