pages/{pageid}/security (PUT)

Overview

Set page security info

Uri Parameters

Name Type Description
pageid string either an integer page ID, "home", or "=" followed by a double uri-encoded page path

Query Parameters

Name Type Description
authenticate bool? Force authentication for request (default: false)
cascade {none,delta,absolute}? none: Permissions are not cascaded to child pages; deltas: Changes between given page's security and proposed security cascaded to child nodes; absolute: Proposed security is set on child pages. Default: none
redirects int? If zero, do not follow page redirects.

Return Codes

Name Value Description
OK 200 The request completed successfully
Bad Request 400 Invalid input parameter or request body
Forbidden 403 Change permissions access to the page is required
Not Found 404 Requested page could not be found

Message Format

Input:

<security>
    <permissions.page>
        <restriction>{text}</restriction> 
    </permissions.page>
    <grants>
        <grant>
            <permissions>
                <role>{text}</role> 
            </permissions>
            <user id="{int}"></user>
            <date.expires>{date}</date.expires> 
        </grant>
        <grant>
            <permissions>
                <role>{text}</role> 
            </permissions>
            <group id="{int}"></group>
            <date.expires>{date}</date.expires> 
        </grant>
        ...
    </grants>
</security>

Output:

<security href="{uri}">
    <permissions.effective>
        <operations mask="{int}">{text}</operations> 
    </permissions.effective>
    <permissions.page>
        <operations mask="{int}">{text}</operations> 
        <restriction>{text}</restriction> 
    </permissions.page>
    <grants>
        <grant>
            <permissions>
                <operations mask="{int}">{text}</operations> 
                <role id="{int}" href="{uri}">{text}</role> 
            </permissions>
            <user id="{int}" href="{uri}">
                <nick>{text}</nick> 
                <username>{text}</username> 
                <email>{text}</email> 
            </user>
            <date.expires>{date}</date.expires> 
            <date.modified>{date}</date.modified> 
            <user.modifiedby id="{int}" href="{uri}">
                <nick>{text}</nick> 
                <username>{text}</username> 
                <email>{text}</email> 
            </user.modifiedby>
        </grant>
        <grant>
            <permissions>
                <operations mask="{int}">{text}</operations> 
                <role id="{int}" href="{uri}">{text}</role> 
            </permissions>
            <group id="{int}" href="{uri}">
                <name>{text}</name> 
            </group>
            <date.expires>{date}</date.expires> 
            <date.modified>{date}</date.modified> 
            <user.modifiedby id="{int}" href="{uri}">
                <nick>{text}</nick> 
                <username>{text}</username> 
                <email>{text}</email> 
            </user.modifiedby>
        </grant>
        ...
    </grants>
</security>

Implementation Notes

The permissions.page element sets the page restriction.  The grants section replaces all existing grants on the page. Use POST:pages/{pageid}/security to add or remove particular grants.

Currently defined page restrictions are:

C# Sample: Set Home Page Security Settings

The following code example sets the home page security settings.  It updates the page restriction to private and grants Contributor access to the user with ID 2.  The grant is set to expire one year from today:

Sample Code

Plug p = Plug.New("http://help.mindtouch.us/@api/deki");
p.At("users", "authenticate").WithCredentials("admin", "password").Get();
XDoc securityDoc = new XDoc("security")
    .Start("permissions.page")
        .Elem("restriction", "Private")
    .End()
    .Start("grants")
        .Start("grant")
            .Start("permissions")
                .Elem("role", "Contributor")
            .End()
            .Start("user").Attr("id", 2).End()
            .Elem("date.expires", DateTime.Today.AddYears(1))
        .End()
    .End();
p.At("pages", "home", "security").Put(securityDoc);

Sample Response from executing Code

<security href="http://help.mindtouch.us/@api/deki/pages/29/security">
    <permissions.effective>
        <operations mask="9223372036854779199">LOGIN,BROWSE,READ,SUBSCRIBE,UPDATE,CREATE,DELETE,CHANGEPERMISSIONS,CONTROLPANEL,ADMIN</operations> 
    </permissions.effective>
    <permissions.page>
        <operations mask="1">LOGIN</operations> 
        <restriction id="3" href="http://help.mindtouch.us/@api/deki/site/roles/3">Private</restriction> 
    </permissions.page>
    <grants>
        <grant>
            <permissions>
                <operations mask="1343">LOGIN,BROWSE,READ,SUBSCRIBE,UPDATE,CREATE,DELETE,CHANGEPERMISSIONS</operations> 
                <role id="4" href="http://help.mindtouch.us/@api/deki/site/roles/4">Contributor</role> 
            </permissions>
            <user id="1" href="http://help.mindtouch.us/@api/deki/users/1">
                <nick>Admin</nick> 
                <username>Admin</username> 
                <email>admin@mindtouch.com</email> 
            </user>
            <date.modified>2007-09-06T06:26:47Z</date.modified> 
            <user.modifiedby id="1" href="http://help.mindtouch.us/@api/deki/users/1">
                <nick>Admin</nick> 
                <username>Admin</username> 
                <email>admin@mindtouch.com</email> 
            </user.modifiedby>
        </grant>
        <grant>
            <permissions>
                <operations mask="1343">LOGIN,BROWSE,READ,SUBSCRIBE,UPDATE,CREATE,DELETE,CHANGEPERMISSIONS</operations> 
                <role id="4" href="http://help.mindtouch.us/@api/deki/site/roles/4">Contributor</role> 
            </permissions>
            <user id="2" href="http://help.mindtouch.us/@api/deki/users/2">
                <nick>Anonymous</nick> 
                <username>Anonymous</username> 
                <email /> 
            </user>
            <date.expires>2008-09-05T07:00:00Z</date.expires> 
            <date.modified>2007-09-06T06:17:23Z</date.modified> 
            <user.modifiedby id="1" href="http://help.mindtouch.us/@api/deki/users/1">
                <nick>Admin</nick> 
                <username>Admin</username> 
                <email>admin@mindtouch.com</email> 
            </user.modifiedby>
        </grant>
    </grants>
</security>

Implementation notes 

  • A grant for Admin is automatically added by the system so that it would not restrict itself from the page.

Curl Sample: Set Page Security Settings

The following command sets the security settings for page "foo" according to the security definitions in document "security.xml":

Sample Code

curl -u admin:password -H "Content-Type: application/xml" -T security.xml -i http://mindtouch.address/@api/deki/pages/=foo/security

Implementation notes 

curl flags

-u
Basic HTTP authentication. Sends a username and password to server so it can verify whether a user is of privilege to perform specific operation.
-H
Adds a header or modifies an existing one. In this case, since an XML document is being sent, the content type must be set to "application/xml". The server will not accept the request otherwise.
-T file
Specifies a PUT command and file that contains the user data.
-i
Includes the HTTP response header in the output. Useful for debugging.

Permissions

ADMIN permission is required to execute above command. Otherwise, a 403 HTTP response (Forbidden) will be returned.

Example

We want to restrict page "Gotham" to "Private" and give specific users certain privileges. User "Batman" will be given a "Contributor" role, allowing him to read, edit, create sub-pages, and so on. Users "Riddler" and "Joker" will be given "Viewer" permission, allowing them to basically only access and read the page. The security definitions are outlined in "gotham.xml".

gotham.xml

Content-Type: application/xml

<security>
	<!-- set "Private" permission -->

	<permissions.page>
		<restriction>Private</restriction>
	</permissions.page>

	<grants>
		<!-- add user "Batman" (user ID 4) with "Contributor" role -->

		<grant>
			<permissions>
				<role>Contributor</role>
			</permissions>
			<user id="4"></user>
		</grant>

		<!-- add users "Joker" and "Penguin (user IDs 5, 6) with "Viewer" role -->

		<grant>
			<permissions>
				<role>Viewer</role>
			</permissions>
			<user id="5"></user>
		</grant>

		<grant>
			<permissions>
				<role>Viewer</role>
			</permissions>
			<user id="6"></user>
		</grant>
	</grants>
</security>

Command Line

curl -u admin:password -H "Content-Type: application/xml" -T gotham.xml -i http://192.168.59.128/@api/deki/pages/=Gotham/security

HTTP Response Headers

HTTP/1.1 200 OK
Date: Wed, 20 Jan 2010 01:23:30 GMT
Server: Dream-HTTPAPI/2.0.0.17629 Microsoft-HTTPAPI/2.0
Content-Length: 2970
Content-Type: application/xml; charset=utf-8
X-Data-Stats: request-time-ms=118; mysql-queries=46; mysql-time-ms=109;
X-Deki-Site: id="default"
Via: 1.1 dekiwiki

HTTP Response Body

Content-Type: application/xml

<?xml version="1.0"?>
<security href="http://192.168.59.128/@api/deki/pages/571/security">
  <permissions.effective>
    <operations mask="9223372036854779903">LOGIN,BROWSE,READ,SUBSCRIBE,UPDATE,CREATE,DELETE,CHANGEPERMISSIONS,CONTROLPANEL,ADMIN</operations>
  </permissions.effective>
  <permissions.page>
    <operations mask="1">LOGIN</operations>
    <restriction id="3" href="http://192.168.59.128/@api/deki/site/roles/3">Private</restriction>
  </permissions.page>
  <grants>
    <grant>
      <permissions>
        <operations mask="1343">LOGIN,BROWSE,READ,SUBSCRIBE,UPDATE,CREATE,DELETE,CHANGEPERMISSIONS</operations>
        <role id="4" href="http://192.168.59.128/@api/deki/site/roles/4">Contributor</role>
      </permissions>
      <user id="4" href="http://192.168.59.128/@api/deki/users/4">
        <nick>Batman</nick>
        <username>Batman</username>
        <email>xxx</email>
        <hash.email>f561aaf6ef0bf14d4208bb46a4ccb3ad</hash.email>
        <uri.gravatar>http://www.gravatar.com/avatar/f561aaf6ef0bf14d4208bb46a4ccb3ad</uri.gravatar>
      </user>
      <date.modified>2010-01-17T02:14:49Z</date.modified>
      <user.modifiedby id="1" href="http://192.168.59.128/@api/deki/users/1">
        <nick>Admin</nick>
        <username>Admin</username>
        <email>admin@admin.com</email>
        <hash.email>64e1b8d34f425d19e1ee2ea7236d3028</hash.email>
        <uri.gravatar>http://www.gravatar.com/avatar/64e1b8d34f425d19e1ee2ea7236d3028</uri.gravatar>
      </user.modifiedby>
    </grant>
    <grant>
      <permissions>
        <operations mask="15">LOGIN,BROWSE,READ,SUBSCRIBE</operations>
        <role id="3" href="http://192.168.59.128/@api/deki/site/roles/3">Viewer</role>
      </permissions>
      <user id="5" href="http://192.168.59.128/@api/deki/users/5">
        <nick>Riddler</nick>
        <username>Riddler</username>
        <email>xxx</email>
        <hash.email>f561aaf6ef0bf14d4208bb46a4ccb3ad</hash.email>
        <uri.gravatar>http://www.gravatar.com/avatar/f561aaf6ef0bf14d4208bb46a4ccb3ad</uri.gravatar>
      </user>
      <date.modified>2010-01-17T02:14:49Z</date.modified>
      <user.modifiedby id="1" href="http://192.168.59.128/@api/deki/users/1">
        <nick>Admin</nick>
        <username>Admin</username>
        <email>admin@admin.com</email>
        <hash.email>64e1b8d34f425d19e1ee2ea7236d3028</hash.email>
        <uri.gravatar>http://www.gravatar.com/avatar/64e1b8d34f425d19e1ee2ea7236d3028</uri.gravatar>
      </user.modifiedby>
    </grant>
    <grant>
      <permissions>
        <operations mask="15">LOGIN,BROWSE,READ,SUBSCRIBE</operations>
        <role id="3" href="http://192.168.59.128/@api/deki/site/roles/3">Viewer</role>
      </permissions>
      <user id="6" href="http://192.168.59.128/@api/deki/users/6">
        <nick>Joker</nick>
        <username>Joker</username>
        <email>xxx</email>
        <hash.email>f561aaf6ef0bf14d4208bb46a4ccb3ad</hash.email>
        <uri.gravatar>http://www.gravatar.com/avatar/f561aaf6ef0bf14d4208bb46a4ccb3ad</uri.gravatar>
      </user>
      <date.modified>2010-01-17T02:14:49Z</date.modified>
      <user.modifiedby id="1" href="http://192.168.59.128/@api/deki/users/1">
        <nick>Admin</nick>
        <username>Admin</username>
        <email>admin@admin.com</email>
        <hash.email>64e1b8d34f425d19e1ee2ea7236d3028</hash.email>
        <uri.gravatar>http://www.gravatar.com/avatar/64e1b8d34f425d19e1ee2ea7236d3028</uri.gravatar>
      </user.modifiedby>
    </grant>
  </grants>
</security>