Skip to main content

users (POST) (MT4)

Overview

Add or modify a user

  • REST Method: POST
  • Method Access: public

Query Parameters

Name Type Description
authenticate bool? Force authentication for request (default: false)
authpassword string? Password to use for verification with external authentication service
authusername string? Username to use for verification with external authentication service
accountpassword string? Account password to set (default: do not set/change password)

Return Codes

Name Value Description
OK 200 The request completed successfully
Bad Request 400 Invalid input parameter or request body
Forbidden 403 Administrator access, apikey, or account owner is required
Not Found 404 Requested user could not be found
Conflict 409 Username conflicts with an existing username

Message Format

Input: 

<user id="{int}">
    <username>{text}</username> 
    <email>{text}</email> 
    <fullname>{text}</fullname> 
    <status>{active|inactive}</status> 
    <service.authentication id="{int}" /> 
    <permissions.user> 
        <role>{text}</role> 
    </permissions.user> 
</user>

Output: 

<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>{text}</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>

Implementation Notes

If no user ID is specified, a new user is created.  Otherwise, the existing user is updated. 

Note that is not possible to create two users having the same username. It is also not possible to modify a username to one that already exists.
 

C# Code Sample: Create New User

The following code example creates "newuser1".  This user has the Contributor role, uses the local authentication service, and has account password "mypassword"

Sample Code

 

Plug p = Plug.New("http://deki-hayes/@api/deki");
p.At("users", "authenticate").WithCredentials("admin", "password").Get();
XDoc usersDoc = new XDoc("user")
     .Elem("username", "newuser1")
     .Elem("email", "newuser1@mindtouch.com")
     .Elem("fullname", "newuser1's full name")
     .Start("permissions.user")
         .Elem("role", "Contributor")
     .End();
p.At("users").With("accountpassword", "mypassword").Post(usersDoc); 

Sample Response from executing Code

 

<user id="3" href="http://deki-hayes/@api/deki/users/3">
   <nick>newuser1</nick>
      <username>newuser1</username>
      <email>newuser1@mindtouch.com</email>
      <fullname>newuser1's full name</fullname>
      <status>active</status>
      <date.lastlogin>2007-09-06T00:56:51Z</date.lastlogin>
      <service.authentication id="1" href="http://deki-hayes/@api/deki/site/services/1" />
      <permissions.user>
         <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>
      <permissions.effective>
         <operations mask="1343">LOGIN,BROWSE,READ,SUBSCRIBE,UPDATE,CREATE,DELETE,CHANGEPERMISSIONS</operations>
      </permissions.effective>
     <groups />
  </user> 

Curl Code Sample: Create New User

The following command line creates a new user according to the XML data in "createuser.xml".

Sample Code

curl -u admin:password -H "Content-Type: application/xml" -d @createuser.xml -i http://mindtouch.address/@api/deki/users

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

The Riddler has invaded Mindtouch! The following will demonstrate how to create a Batman user to administer swift justice. Below is an XML document with all the necessary data to create the user.

batman.xml

Content-Type: application/xml

<user>
    <username>Batman</username> 
    <email>alfred@batcave.com</email> 
    <fullname>I am the Batman</fullname> 
    <status>active</status> 
</user>

Command Line

curl -u admin:password -H "Content-Type: application/xml" -d @batman.xml -i http://192.168.168.110/@api/deki/users

HTTP Response Headers

HTTP/1.1 200 OK
Date: Wed, 06 Jan 2010 01:29:35 GMT
Server: Dream-HTTPAPI/1.7.0.16080
X-Deki-Site: id="default"
Content-Type: application/xml; charset=utf-8
Content-Length: 1246
Via: 1.1 dekiwiki

HTTP Response Body

Content-Type: application/xml

<?xml version="1.0"?>
<user id="3" href="http://192.168.168.110/@api/deki/users/3">
  <nick>Batman</nick>
  <username>Batman</username>
  <email>alfred@batcave.com</email>
  <hash.email>d46d8fa3b6c7af9b1794aa260b38a89e</hash.email>
  <uri.gravatar>http://www.gravatar.com/avatar/d46d8fa3b6c7af9b1794aa260b38a89e</uri.gravatar>
  <date.created>2010-01-04T22:55:32Z</date.created>
  <page.home id="41" href="http://192.168.168.110/@api/deki/pages/41?redirects=0">
    <uri.ui>http://192.168.168.110/User:Batman</uri.ui>
    <title>User:Batman</title>
    <path>User:Batman</path>
    <namespace>user</namespace>
  </page.home>
  <fullname>I am the Batman</fullname>
  <status>active</status>
  <date.lastlogin>2010-01-04T22:55:31Z</date.lastlogin>
  <language/>
  <timezone/>
  <service.authentication id="1" href="http://192.168.168.110/@api/deki/site/services/1"/>
  <permissions.user>
    <operations mask="1343">LOGIN,BROWSE,READ,SUBSCRIBE,UPDATE,CREATE,DELETE,CHANGEPERMISSIONS</operations>
    <role id="4" href="http://192.168.168.110/@api/deki/site/roles/4">Contributor</role>
  </permissions.user>
  <permissions.effective>
    <operations mask="1343">LOGIN,BROWSE,READ,SUBSCRIBE,UPDATE,CREATE,DELETE,CHANGEPERMISSIONS</operations>
  </permissions.effective>
  <groups/>
  <properties href="http://192.168.168.110/@api/deki/users/3/properties"/>
</user>

Notes

  • Attempting to create a user of the same name will result in a 409 HTTP response (Conflict).
  • Was this article helpful?