[Q&A Friday] How to Manage Users with the REST API

Fri 28 February 2014 By Laurent Doguin

How to Manage User with the REST API How to Manage Users with the REST API

Today we have a question from Christian who asks how to create a user using the REST API. Using this API, you'll have access to several resources endpoints (document, user, group, automation) as well as several adapters (children, search, page provider, ACL, audit, business objects..).

So here's how to use the user endpoint.

Get a User

If I want to get information about a particular user, I can simply go to the following URL: http://localhost:8080/nuxeo/api/v1/user/ldoguin

This will return a JSON answer looking like this:

{ "entity-type" : "user",
"extendedGroups" : [ { "label" : "Administrators group",
"name" : "administrators",
"url" : "group/administrators"
} ],
"id" : "ldoguin",
"isAdministrator" : true,
"isAnonymous" : false,
"properties" : { "company" : "Nuxeo",
"email" : "[email protected]",
"firstName" : "Laurent",
"groups" : [ "administrators" ],
"lastName" : "Doguin",
"password" : "",
"username" : "ldoguin"

Take a close look at the object returned, it's important for what's coming next. What's interesting here is the entity-type property set to user.

Create a User

To create a new user, you have to send a POST request with the following data to this URL:


Using curl, it would look like this:

curl -X POST -H "Content-Type: application/json" -u Administrator:Administrator -d "{ "entity-type": "user", "id":"psteele", "properties":{"username":"psteele", "email":"[email protected]", "lastName":"Steele", "firstName":"Peter", "password":"psteele" } }" http://localhost:8080/nuxeo/api/v1/user

The JSON answer should look like this:

{ "entity-type" : "user",
"id" : "psteele",
"extendedGroups" : [ ],
"isAdministrator" : false,
"isAnonymous" : false,
"properties" : { "company" : "Green Man",
"email" : "[email protected]",
"firstName" : "Peter",
"username" : "psteele",
"groups" : [ ],
"lastName" : "Steele",
"password" : "",
"company": null

Be very careful about the escaping. Again the entity-type property is set to user. This is why Christian had an issue in the first place, as he was using NuxeoPrincipal as entity-type.

Modify a User

I forgot to add the company of the user during its creation. It's easy to modify. Here's another curl example:

curl -X PUT -H "Content-Type: application/json" -u Administrator:Administrator -d "{ "entity-type": "user", "id":"psteele", "properties":{"company":"SUPERGREEN"}}" http://localhost:8080/nuxeo/api/v1/user/psteele

First big difference with the previous call is that you need to add the user id at the end of the URL. It's a resource endpoint so you need to identify that resource. Second difference - we use PUT for modification instead of POST. And last, you don't need to put all existing information, you can simply add the properties to modify. Just know that the id is mandatory.

Delete a User

Since this was just for test/demonstration purposes, let's remove that user:

curl -X DELETE -u Administrator:Administrator http://localhost:8080/nuxeo/api/v1/user/psteele

As you can see this is much simpler. You still have the user id at the end of the URL. There is no JSON needed in the request body, just make sure you use DELETE.

Category: Product & Development
Tagged: How to, Q&A, REST API