pages/{pageid}/security (POST)

Overview

Modify page security by adding and removing grants

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} Apply proposed security to 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.added>
        <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.added>
    <grants.removed>
        <grant>
            <permissions>
                <role>{text}</role> 
            </permissions>
            <user id="{int}"></user>
        </grant>
        <grant>
            <permissions>
                <role>{text}</role> 
            </permissions>
            <group id="{int}"></group>
        </grant>
        ...
    </grants.removed>
</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.added section grants permissions to particular users or groups.  The grants.removed section removes permissions from particular users or groups.  Use PUT:pages/{pageid}/security to entirely replace the page grants.

Currently defined page restrictions are:

The data submitted must be sent with a MIME type of application/xml.

C# Code Sample: Modify Page Security Settings

The following code example modifies the home page security settings.  It sets 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://dekiwiki/@api/deki");
p.At("users", "authenticate").WithCredentials("admin", "password").Get();
XDoc securityDoc = new XDoc("security")
    .Start("permissions.page")
        .Elem("restriction", "Private")
    .End()
    .Start("grants.added")
        .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").Post(securityDoc);

Sample Response from executing Code

After pasting the sample code in here, select the correct syntax highlighting from the Transformations button in the toolbar

Curl Code Sample: Modify Page Security Settings

The following command updates the security settings for page "foo" using the security definitions outlined in "security.xml".

Sample Code

curl -u admin:password -H "Content-Type: application/xml" -d @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.
-d @file
Specifies the .xml 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

User "Spock" has been demoted to Viewer privileges, which precludes him from editing pages. However, we want to give him a "Contributor" role to page "Starfleet", allowing him to read and edit the page. That would be very logical. We also want to set the page to private so pesky Klingons cannot vandalize it.

spockurity.xml

Content-Type: application/xml

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

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

	<!-- add user "Spock" (user ID 78) with "Contributor" role -->

	<grants.added>
		<grant>
			<permissions>
				<role>Contributor</role>
			</permissions>
			<user id="78"></user>
		</grant>
	</grants.added>
</security>

Command Line

curl -u admin:password -H "Content-Type: application/xml" -d @spockurity.xml -i http://192.168.59.128/@api/deki/pages/=Starfleet/security

HTTP Response Headers

HTTP/1.1 200 OK
Date: Tue, 19 Jan 2010 23:41:07 GMT
Server: Dream-HTTPAPI/2.0.0.17629 Microsoft-HTTPAPI/2.0
Content-Length: 2214
Content-Type: application/xml; charset=utf-8
X-Data-Stats: request-time-ms=99; mysql-queries=28; mysql-time-ms=88;
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/569/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="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>
      <date.modified>2010-01-17T00:19:19Z</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="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="78" href="http://192.168.59.128/@api/deki/users/78">
        <nick>spock</nick>
        <username>spock</username>
        <email>spock@vulcan.com</email>
        <hash.email>febf25b1653f915fd76f9786321517b7</hash.email>
        <uri.gravatar>http://www.gravatar.com/avatar/febf25b1653f915fd76f9786321517b7</uri.gravatar>
      </user>
      <date.modified>2010-01-17T00:32:29Z</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>