pages/{pageid}/security (POST)
Overview
Modify page security by adding and removing grants
- REST Method: POST
- 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} | 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:
- 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
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>