POST /manage/v2/users

Summary

This resource address creates a new user in the security database.

Response

Upon success, MarkLogic Server returns status code 201 (Created). If the user already exists or if the payload is malformed, a status code of 400 (Bad Request) is returned. A status code of 401 (Unauthorized) is returned if the user does not have the necessary privileges.

Required Privileges

• the manage-admin and security role
• the following privileges:

  http://marklogic.com/xdmp/privileges/manage

  http://marklogic.com/xdmp/privileges/manage-admin

  http://marklogic.com/xdmp/privileges/create-user

• the manage role, http://marklogic.com/xdmp/privileges/manage plus the following granular privileges:
  • http://marklogic.com/xdmp/privileges/create-data-user and
    http://marklogic.com/xdmp/privileges/user-set-queries to create users with queries.
  • http://marklogic.com/xdmp/privileges/user/inherit/user-ID

Usage Notes

The structure of the data in the request body is shown below. The user-name property is required. In MarkLogic Server 9.0-8 and earlier, the password property is also required. Starting in MarkLogic Server 9.0-9, if the password property is not provided, a strong, random password will be generated. In 10.0-7, the property queries was added.

Note: The properties described here are for XML payloads. In general they are the same for JSON, with the exception that, in JSON, roles, external-names, permissions, collections and queriesare expressed in singular form. For example, in JSON, permissions is instead permission and the format is: "permission":[{"role-name":"name", "capability":"cap"}]. Please pay special attention that the singular form of queries is capability-query.

user-name

User/login name (unique)

description

An object's description.

password

Password.

external-names

The external names specifications.

This is a complex structure with the following children:

external-name

The name used to match external group name.

roles

The roles assigned. The roles assigned to the user.

This is a complex structure with the following children:

role

A role identifier (unique key).

permissions

The default set of permissions used in document creation.

This is a complex structure with the following children:

permission

Permission representation.

This is a complex structure with the following children:

role-name

A role name.

capability

The action/task permitted by a permission

collections

The default set of collections used in document creation.

This is a complex structure with the following children:

collection

The collection uri.

queries

This is a complex structure with the following children:

capability-query

This is a complex structure with the following children:

capability

The action/task permitted by a permission

query

This is a complex structure with the following children:

cts:query

Example

curl -X POST  --anyauth -u admin:admin --header "Content-Type:application/json" \
-d '{"user-name":"joe", 
     "password": "cool",
     "role": [ "rest-reader", "rest-writer" ] 
    }' \
http://localhost:8002/manage/v2/users

==>  Creates a user, named '"joe" with the "rest-reader" and "rest-writer" 
     roles, in the Security database. 
    

Example

// JSON payload example for creating a user with queries.

$ cat payload.json

{
  "user-name": "Vanessa",
  "password": "strongpassword",
  "description": "Software development engineer",
  "capability-query": [{
    "capability":"read", 
    "query": {
      "elementQuery": {
        "element": ["metadata"], 
        "query": {
          "elementWordQuery": {
            "element": ["region"], 
            "text": ["NA"], 
            "options": ["lang=en"]
          }
        }
      }
    }
  }]
}
  
curl -X POST -i --digest -u admin:admin -H "Content-Type:application/json" \
-d @payload.json http://localhost:8002/manage/v2/users

==> Creates a user, named "Vanessa", with user queries for "read", in the Security Database.
    

Example

(: XML payload for creating a user with queries :)

$ cat payload.xml

<user-properties xmlns="http://marklogic.com/manage/user/properties">
  <user-name>Vanessa</user-name>
  <password>strongpassword</password>
  <description>Software development engineer</description>
  <queries>
    <capability-query>
      <capability>read</capability>
      <query>
        <cts:element-query xmlns:cts="http://marklogic.com/cts">
          <cts:element>metadata</cts:element>
          <cts:element-word-query>
            <cts:element>region</cts:element>
            <cts:text xml:lang="en">NA</cts:text>
          </cts:element-word-query>
        </cts:element-query>
      </query>
    </capability-query>
  </queries>
</user-properties>

curl -X POST -i --digest -u admin:admin -H "Content-Type:application/xml" \
-d @payload.xml http://localhost:8002/manage/v2/users

==> Creates a user, named "Vanessa", with user queries for "read", in the Security Database.