Sharing

Nick comes with a sophisticated user management system that allows to assign users and groups with global roles and permissions. Sometimes this in not enough though and you might want to give users the permission to access or edit a specific part of your website or a specific content object. This is where local roles located in the sharing tab come in handy.

Retrieving Local Roles

The sharing information of a content object can be accessed by appending /@sharing to the GET request to the URL of a content object. E.g. to access the sharing information for a top-level folder, do:

GET /@sharing HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

HTTP/1.1 200 OK
Content-Type: application/json

{
  "available_roles": [
    {
      "id": "Anonymous",
      "title": "Anonymous"
    },
    {
      "id": "Authenticated",
      "title": "Authenticated"
    },
    {
      "id": "Owner",
      "title": "Owner"
    },
    {
      "id": "Reader",
      "title": "Reader"
    },
    {
      "id": "Contributor",
      "title": "Contributor"
    },
    {
      "id": "Editor",
      "title": "Editor"
    },
    {
      "id": "Reviewer",
      "title": "Reviewer"
    },
    {
      "id": "Administrator",
      "title": "Administrator"
    }
  ],
  "entries": [],
  "inherit": true
}

The available_roles property contains the list of roles that can be managed via the sharing page. It contains dictionaries with the role ID and its translated title (as it appears on the sharing page).

Searching for principles

Users and/or groups without a sharing entry can be found by appending the argument search to the query string. ie ?search=admin. Global roles are marked with the string global. Inherited roles are marked with the string acquired.

GET /@sharing?search=admin HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

HTTP/1.1 200 OK
Content-Type: application/json

{
  "available_roles": [
    {
      "id": "Anonymous",
      "title": "Anonymous"
    },
    {
      "id": "Authenticated",
      "title": "Authenticated"
    },
    {
      "id": "Owner",
      "title": "Owner"
    },
    {
      "id": "Reader",
      "title": "Reader"
    },
    {
      "id": "Contributor",
      "title": "Contributor"
    },
    {
      "id": "Editor",
      "title": "Editor"
    },
    {
      "id": "Reviewer",
      "title": "Reviewer"
    },
    {
      "id": "Administrator",
      "title": "Administrator"
    }
  ],
  "entries": [
    {
      "id": "admin",
      "title": "Admin",
      "roles": {
        "Anonymous": false,
        "Authenticated": false,
        "Owner": false,
        "Reader": false,
        "Contributor": false,
        "Editor": false,
        "Reviewer": false,
        "Administrator": "global"
      },
      "type": "user"
    },
    {
      "id": "Administrators",
      "title": "Administrators",
      "roles": {
        "Anonymous": false,
        "Authenticated": false,
        "Owner": false,
        "Reader": false,
        "Contributor": false,
        "Editor": false,
        "Reviewer": false,
        "Administrator": "global"
      },
      "type": "group"
    }
  ],
  "inherit": true
}

Updating Local Roles

You can update the sharing information by sending a POST request to the object URL and appending /@sharing, e.g. /news/@sharing. E.g. say you want to give the Administrators group the Reader local role for a folder:

POST /@sharing HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk
Content-Type: application/json

{
  "entries": [
    {
      "id": "Administrators",
      "roles": {
        "Contributor": true,
        "Reader": true
      },
      "type": "user"
    }
  ],
  "inherit": true
}

HTTP/1.1 204 No Content