pages/{pageid}/security (PUT)
Overview
Set page security info
- REST Method: PUT
- Method Access: public
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:
- Public: All users can read and edit
- Semi-Public: All users can read, but only selected users can edit
- Private: Only selected users can read and edit
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>