POST:pages/{pageid}/security

Overview

public. Modify page security by adding and removing grants

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
  

Use GET:site/roles to retrieve a list of roles currently defined for the site.

Code Samples

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:

Plug p = Plug.New("http://deki-hayes/@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 with the new security settings.  Note that the system automatically added a grant for Admin so that it would not restrict itself from the page:

<security href="http://deki-hayes/@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://deki-hayes/@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://deki-hayes/@api/deki/site/roles/4">Contributor</role> 
            </permissions>
            <user id="1" href="http://deki-hayes/@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://deki-hayes/@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://deki-hayes/@api/deki/site/roles/4">Contributor</role> 
            </permissions>
            <user id="2" href="http://deki-hayes/@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://deki-hayes/@api/deki/users/1">
                <nick>Admin</nick> 
                <username>Admin</username> 
                <email>admin@mindtouch.com</email> 
            </user.modifiedby>
        </grant>
    </grants>
</security>