users/{userid}/allowed (POST)

Overview

Check one or more resources if given operation is allowed.

REST Method: POST
Method Access: public

Uri Parameters

Name	Type	Description
userid	string	either an integer user ID, "current", or "=" followed by a double uri-encoded user name

Query Parameters

Name	Type	Description
mask	long?	Permission bit mask required for the pages
verbose	bool?	Return verbose information on permitted pages (default: true
authenticate	bool?	Force authentication for request (default: false)
operations	string?	Comma separated list of operations to verify
invert	bool?	Return filtered instead of allowed pages. Sets verbose to false (default: false

Return Codes

Name	Value	Description
OK	200	The request completed successfully
Bad Request	400	Invalid input parameter or request body
Not Found	404	Requested user could not be found

Message Format

Input:

<pages>
    <page id="{int}"/>
    ...
</pages>

Output:

<pages>
    <page id="{int}" href="{uri}">
        <title>{text}</title>
        <path>{text}</path>
    </page>
    ...
</pages>

Implementation Notes

Use GET:site/operations to retrieve a list of all operations currently defined on the site.

C# Sample: Check Anonymous User Login and Read Access

The following code example checks whether the Anonymous user has LOGIN and READ access to pages with ID 29 and 31

Sample Code

Plug p = Plug.New("http://deki-hayes/@api/deki");
p.At("users", "authenticate").WithCredentials("admin", "password").Get();
XDoc pagesDoc = new XDoc("pages")
    .Start("page")
        .Attr("id", 29)
    .End()
    .Start("page")
        .Attr("id", 31)
    .End();
p.At("users", "=Anonymous", "allowed").With("operations", "LOGIN,READ").Post(pagesDoc);

Sample Response from executing Code

<?xml version="1.0"?>
<pages>
  <page id="29" href="http://deki-hayes/@api/deki/pages/29">
    <title>DekiWiki (Hayes)</title>
    <path/>
  </page>
</pages>

Curl Sample: Check User Access

The following curl command returns a sublist of pages user "foo" is allowed to access from a list of pages in "pages.xml".

Sample Code

curl -u username:password -H "Content-Type: application/xml" -d @pages.xml -i http://mindtouch.address/@api/deki/users/=foo/allowed

Implementation notes

Operations and Mask

Sending the above command without the operations or mask parameters does not yield a response of interest. This is because the command will match the user with every page permission, and thus will simply return the list of pages sent in the request. To receive a useful response, such as what pages the specific user is allowed to read, update, set permissions, and so on, an "operations" or "mask" parameter is appended to the end of the path.; For example, the following command will check if user "foo" has READ, UPDATE, and LOGIN access for the list of pages in "pages.xml":

curl -u username:password -H "Content-Type: application/xml" -d @pages.xml -i http://mindtouch.address/@api/deki/users/=foo/allowed?operations="READ,UPDATE,LOGIN"

The response will contain a list where user foo has one or more of those permissions. The "mask" parameter is the same as operations, except it substitutes numeric values for permissions. The following command is interchangeable to the one above:

curl -u username:password -H "Content-Type: application/xml" -d @pages.xml -i http://mindtouch.address/@api/deki/users/=foo/allowed?mask="21"

Where LOGIN = 1, READ = 4, and UPDATE = 16 (16 + 4 + 1 = 21).

Permission Enumeration

NONE	0
LOGIN	1
BROWSE	2
READ	4
SUBSCRIBE	8
UPDATE	16
CREATE	32
DELETE	256
CHANGEPERMISSION	1024
CONTROLPANEL	2048
UNSAFECONTENT	4096
ADMIN	0x8000000000000000L

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.
-d @file: Specifies a POST request and file to send.
-H: Replaces or appends an HTTP header. The "Content-Type" header specifies the MIME type of the value attached to the property. In this case, use application/xml since the document being passed is of type XML.
-i: Includes the HTTP response header in the output. Useful for debugging.

Example

The user "spock" has been given a "Viewer" role, giving him permissions LOGIN, BROWSE, READ, SUBSCRIBE. We want to see what pages in pages.xml Spock has permission to READ.

pages.xml

Content-Type: text/plain

<pages>
	<page id="565"/>
	<page id="562"/>
	<page id="563"/>
	<page id="564"/> <!-- This page has been set to Private -->
</pages>

Sample Code

curl -u admin:password -H "Content-Type: application/xml" -d @pages.xml -i http://192.168.59.128/@api/deki/users/=spock/allowed?operations="READ"

HTTP Response Headers

HTTP/1.1 200 OK
Date: Fri, 15 Jan 2010 22:11:23 GMT
Server: Dream-HTTPAPI/1.7.2.17433
X-Deki-Site: id="default"
Content-Type: application/xml; charset=utf-8
Content-Length: 661
Via: 1.1 dekiwiki

HTTP Response Body

Content-Type: application/xml

<?xml version="1.0"?>
<pages>
  <page id="565" href="http://192.168.59.128/@api/deki/pages/565?redirects=0">
    <uri.ui>http://192.168.59.128/Bar</uri.ui>
    <title>Bar</title>
    <path>Bar</path>
    <namespace>main</namespace>
  </page>
  <page id="562" href="http://192.168.59.128/@api/deki/pages/562?redirects=0">
    <uri.ui>http://192.168.59.128/Test</uri.ui>
    <title>Test</title>
    <path>Test</path>
    <namespace>main</namespace>
  </page>
  <page id="563" href="http://192.168.59.128/@api/deki/pages/563?redirects=0">
    <uri.ui>http://192.168.59.128/Test/Foo</uri.ui>
    <title>Foo</title>
    <path>Test/Foo</path>
    <namespace>main</namespace>
  </page>
</pages>

As you can see, page with ID = 564 is not included since it is marked private. Thus it can be gathered that user "spock" does not have privilege to READ said page.