Skip to main content

 

MindTouch Success Center

users (GET) (MT4)

Overview

Retrieve list of users.

  • REST Method: GET
  • Method Access: public

Query Parameters

Name Type Description
authenticate bool? Force authentication for request (default: false)
verbose bool? Return detailed user information. (default: true)
sortby {id, username, nick, email, fullname, date.lastlogin, status, role, service, date.created}? Sort field. Prefix value with '-' to sort descending. default: No sorting
offset int? Number of items to skip. Must be a positive number or 0 to not skip any. (default: 0)
limit string? Maximum number of items to retrieve. Must be a positive number or 'all' to retrieve all items. (default: 100)
seatfilter string? Search for users with or without seats (one of "seated", "unseated", or "recommended"; default: none)
activatedfilter bool? Search for users by their active status
rolefilter string? Search for users by a role name
authprovider int? Return users belonging to given authentication service id
usernameemailfilter string? Search for users by name and email or part of a name and email
fullnamefilter string? Search for users full name starting with supplied text
usernamefilter string? Search for users name starting with supplied text

Return Codes

Name Value Description
OK 200 The request completed successfully
Forbidden 403 Read access is required

Message Format

Output: 

<users count="{int}" href="{uri}">
    <user id="{int}" href="{uri}">
        <nick>{text}</nick> 
        <username>{text}</username> 
        <email>{text}</email> 
        <page.home id="{int}" href="{int}">
            <title>{text}</title> 
            <path>{text}</path> 
        </page.home>
        <fullname /> 
        <status>{active|inactive}</status> 
        <date.lastlogin>{date}</date.lastlogin> 
        <service.authentication id="{int}" href="{uri]" /> 
        <permissions.user>
            <operations mask="{int}">{text}</operations> 
            <role id="{int}" href="{uri}">{text}</role> 
        </permissions.user>
        <permissions.effective>
            <operations mask="{int}">{text}</operations> 
        </permissions.effective>
        <groups count="{int}" href="{uri}">  
            <group id="{int}" href="{uri}">  
                <name>{text}</name>   
                <service.authentication id="{int}" href="{uri}" />   
                <users count="{int}" href="{uri}" />   
                <permissions.group>  
                    <operations mask="{int}">{text}</operations>   
                    <role id="{int}" href="{uri}">{text}</role>   
               </permissions.group>  
           </group>  
           ...
       </groups> 
    </user>
    ...
</users>

Implementation Notes

User POST:users to add or modify users.

C# Code Sample: Retrieve User List

The following code example retrieves a list of users:

Sample Code

Plug p = Plug.New("http://help.mindtouch.us/@api/deki");
p.At("users", "authenticate").WithCredentials("admin", "password").Get();
p.At("users").Get();

Sample Response from executing Code

Sample response indicating that there are two users, Admin and Anonymous:

<users count="2" href="http://help.mindtouch.us/@api/deki/users">
    <user id="1" href="http://help.mindtouch.us/@api/deki/users/1">
        <nick>Admin</nick>
        <username>Admin</username>
        <email>admin@mindtouch.com</email>
        <page.home id="30" href="http://help.mindtouch.us/@api/deki/pages/30">
            <title>User:Admin</title>
            <path>User:Admin</path>
        </page.home>
        <fullname></fullname>
        <status>active</status>
        <date.lastlogin>2007-08-30T17:26:32Z</date.lastlogin>
        <service.authentication id="1" href="http://help.mindtouch.us/@api/deki/site/services/1" />
        <permissions.user>
            <operations mask="9223372036854779903">LOGIN,BROWSE,READ,SUBSCRIBE,UPDATE,CREATE,DELETE,CHANGEPERMISSIONS,CONTROLPANEL,ADMIN</operations>
            <role id="5" href="http://help.mindtouch.us/@api/deki/site/roles/5">Admin</role>
        </permissions.user>
        <permissions.effective>
            <operations mask="9223372036854779903">LOGIN,BROWSE,READ,SUBSCRIBE,UPDATE,CREATE,DELETE,CHANGEPERMISSIONS,CONTROLPANEL,ADMIN</operations>
        </permissions.effective>
        <groups />
    </user>
    <user id="2" href="http://help.mindtouch.us/@api/deki/users/2">
        <nick>Anonymous</nick>
        <username>Anonymous</username>
        <email></email>
        <fullname>Anonymous User</fullname>
        <status>active</status>
        <date.lastlogin>2007-08-30T17:26:12Z</date.lastlogin>
        <service.authentication id="1" href="http://help.mindtouch.us/@api/deki/site/services/1" />
        <permissions.user>
            <operations mask="15">LOGIN,BROWSE,READ,SUBSCRIBE</operations>
            <role id="3" href="http://help.mindtouch.us/@api/deki/site/roles/3">Viewer</role>
        </permissions.user>
        <permissions.effective>
            <operations mask="15">LOGIN,BROWSE,READ,SUBSCRIBE</operations>
        </permissions.effective>
        <groups />
    </user>
</users>

Curl Code Sample: Retrieve User List

The following command retrieves a list of all users registered to the site:

Sample Code

curl -u username:password -i http://mindtouch.address/@api/deki/users

Sample Response from executing Code

Sample response with a looong list of users (only a couple shown).

Content-Type: application/xml

<users count="90" querycount="90" totalcount="90" href="http://192.168.59.128/@api/deki/users">
  <user id="1" href="http://192.168.59.128/@api/deki/users/1">
    <nick>Admin</nick>
    <username>Admin</username>
    <email hidden="true"/>
    <hash.email>64e1b8d34f425d19e1ee2ea7236d3028</hash.email>
    <uri.gravatar>http://www.gravatar.com/avatar/64e1b8d34f425d19e1ee2ea7236d3028</uri.gravatar>
    <date.created>0001-01-01T00:00:00Z</date.created>
    <page.home id="37" href="http://192.168.59.128/@api/deki/pages/37?redirects=0">
      <uri.ui>http://192.168.59.128/User:Admin</uri.ui>
      <title>User:Admin</title>
      <path>User:Admin</path>
      <namespace>user</namespace>
    </page.home>
    <fullname/>
    <status>active</status>
    <date.lastlogin>2010-02-02T19:44:00Z</date.lastlogin>
    <language/>
    <timezone/>
    <service.authentication id="1" href="http://192.168.59.128/@api/deki/site/services/1"/>
    <permissions.user>
      <operations mask="9223372036854779903">LOGIN,BROWSE,READ,SUBSCRIBE,UPDATE,CREATE,DELETE,CHANGEPERMISSIONS,CONTROLPANEL,ADMIN</operations>
      <role id="5" href="http://192.168.59.128/@api/deki/site/roles/5">Admin</role>
    </permissions.user>
    <permissions.effective>
      <operations mask="9223372036854779903">LOGIN,BROWSE,READ,SUBSCRIBE,UPDATE,CREATE,DELETE,CHANGEPERMISSIONS,CONTROLPANEL,ADMIN</operations>
    </permissions.effective>
    <groups/>
    <properties href="http://192.168.59.128/@api/deki/users/1/properties"/>
  </user>
  <user id="2" href="http://192.168.59.128/@api/deki/users/2">
    <nick>Anonymous</nick>
    <username>Anonymous</username>
    <email/>
    <hash.email>d41d8cd98f00b204e9800998ecf8427e</hash.email>
    <uri.gravatar>http://www.gravatar.com/avatar/d41d8cd98f00b204e9800998ecf8427e</uri.gravatar>
    <date.created>0001-01-01T00:00:00Z</date.created>
    <fullname>Anonymous User</fullname>
    <status>active</status>
    <date.lastlogin>2010-02-02T19:51:58Z</date.lastlogin>
    <language/>
    <timezone/>
    <service.authentication id="1" href="http://192.168.59.128/@api/deki/site/services/1"/>
    <permissions.user>
      <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>
    <permissions.effective>
      <operations mask="15">LOGIN,BROWSE,READ,SUBSCRIBE</operations>
    </permissions.effective>
    <groups/>
    <properties count="0" href="http://192.168.59.128/@api/deki/users/2/properties"/>
  </user>

  ...

</users>

Implementation notes 

curl flags

-u
Provides external user authentication. Note that if anonymous access is available and authentication is not forced, this flag may be omitted.
-i
Outputs the HTTP response headers. Useful for debugging.
  • Was this article helpful?