—Rate this article—
 

Creating users

See all application entities

A user entity represents an application user. Using API Services you can create, retrieve, update, delete, and query user entities. See User entity properties for a list of the system-defined  properties for user entities. In addition, you can create user properties specific to your application.

Request Syntax

curl -X POST "https://api.usergrid.com/your-org/your-app/users" '{ request body }'

Use the POST method to create a new user in the users collection.

Request URI

POST /<org_id>/<app_id>/users

Parameters

Parameter Description
uuid | org_id Organization UUID or organization name.
uuid | app_id Application UUID or application name.
request body

One or more sets of user properties, of which username is mandatory and must be unique:

{
    "username" : "john.doe",
    "email" : "john.doe@gmail.com",
    "name" : "John Doe",
    "password" : "test1234"
}

Although the password parameter is not mandatory, if you don't specify it, the user will not be able to log in using username and password credentials. If a password is not specified for the user, and you're an Admin, you can set a password for the user (see Setting a password).

Note: The username can contain any combination of characters, including those that represent letters, numbers, and symbols.

Example

Note: Although not shown in the API examples below, you need to provide a valid access token with each API call. See Authenticating users and application clients for details.

Request

curl -X POST "https://api.usergrid.com/my-org/my-app/users" -d '{"username":"john.doe","email":"john.doe@gmail.com","name":"John Doe"}'

Response

{
  "action" : "post",
  "application" : "db1e60a0-417f-11e3-9586-0f1ff3650d20",
  "params" : { },
  "path" : "/users",
  "uri" : "https://api.usergrid.com/steventraut/mynewapp/users",
  "entities" : [ {
    "uuid" : "8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc",
    "type" : "user",
    "name" : "John Doe",
    "created" : 1390533228622,
    "modified" : 1390533228622,
    "username" : "john.doe",
    "email" : "john.doe@gmail.com",
    "activated" : true,
    "picture" : "http://www.gravatar.com/avatar/e13743a7f1db7f4246badd6fd6ff54ff",
    "metadata" : {
      "path" : "/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc",
      "sets" : {
        "rolenames" : "/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc/roles",
        "permissions" : "/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc/permissions"
      },
      "collections" : {
        "activities" : "/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc/activities",
        "devices" : "/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc/devices",
        "feed" : "/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc/feed",
        "groups" : "/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc/groups",
        "roles" : "/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc/roles",
        "following" : "/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc/following",
        "followers" : "/users/8ae8a6ea-84a5-11e3-884d-f18e8f6fb3bc/followers"
      }
    }
  }],
  "timestamp" : 1390533228619,
  "duration" : 142,
  "organization" : "my-org",
  "applicationName" : "my-app"
}

These are ApigeeDataClient methods for adding users to your data store.

Synchronous

-(ApigeeClientResponse *)addUser:(NSString *)username
                           email:(NSString *)email
                            name:(NSString *)name
                        password:(NSString *)password;

Asynchronous

-(ApigeeClientResponse *)addUser:(NSString *)username 
                           email:(NSString *)email 
                            name:(NSString *)name 
                        password:(NSString *)password 
               completionHandler:(ApigeeDataClientCompletionHandler)completionHandler;

Parameters

Parameter Description
completionHandler A handler to receive the response from an asynchronous call.
email The user's email address. This must be unique in your data store.
name A friendly name for the user.
password A password with which the user can log in.
username The username value with which the user will log in. This must be unique in your data store. The string may only include A-Z, a-z, 0-9, dot, underscore and dash. It must be between 4 and 15 characters.

Example

In this example, the code to add a user is within code that checks to see if the requested username already exists. This example uses the iOS SDK.

// Values with which to create the new group.
NSString *username = @"johndoe";
NSString *name = @"John Doe";
NSString *email = @"johndoe@example.com";
NSString *password = @"johnsdogsname";

// Create a query instance specifying the path that
// was requested for the new group.
ApigeeQuery *query = [ [ApigeeQuery alloc] init];    
[query addRequirement:[NSString stringWithFormat:@"username='%@'", username]];

// Find out if there's already a user with this username. Some callback
// methods have been omitted.
[[apigeeClient dataClient] getUsers:query
                  completionHandler:^(ApigeeClientResponse *usersResponse)
{
     if ([usersResponse completedSuccessfully])
     {
         if ([usersResponse.response[@"entities"] count] > 0)
         {
             // If an entity was returned, display a message telling
             // the user that their username is taken.
         } else {
            // Add a new user with an async SDK method.
            [[apigeeClient dataClient] addUser:username
                                         email:email
                                          name:name
                                      password:password
                             completionHandler:^(ApigeeClientResponse *response)
            {
                if ([response completedSuccessfully])
                {
                    // Do something after a successful request.
                } else {
                    // Display or log a message if the request was 
                    // unsuccessful.
                }
            }];
         }
     } else {
         // Log or display a message.
     }
}];

These are DataClient methods for adding users to your data store.

Synchronous

public ApiResponse createUser(String username, 
                              String name, 
                              String email, 
                              String password)

Asynchronous

public void createUserAsync(final String username, 
                            final String name, 
                            final String email, 
                            final String password, 
                            final ApiResponseCallback callback)

Parameters

Parameter Description
callback A handler to receive the response from an asynchronous call.
email The user's email address. This must be unique in your data store.
name A friendly name for the user.
password A password with which the user can log in.
username The username value with which the user will log in. This must be unique in your data store. The string may only include A-Z, a-z, 0-9, dot, underscore and dash. It must be between 4 and 15 characters.

Example

In this example, the code to add a user is within code that checks to see if the requested username already exists. This example uses the Android SDK.

// Handles on widgets in the UI.
String userName = "johndoe";
String name = "John Doe";
String email = "johndoe@example.com";
String password = "johnsdogsname";

// A query statement with which to check for an existing user
// with the same username (which must be unique).
String queryText = "username='" + userName + "'";

// Call the DataClient method to find out if there's already
// a user with the user value the user entered. If not, add
// the user. Some callback methods are omitted for brevity.
client.queryUsersAsync(queryText, new QueryResultsCallback() {

    // Called to receive the query response.
    @Override
    public void onResponse(Query query) {
        ApiResponse response = query.getResponse();

        // Get the list of users returned by the query.
        List<Entity> users = response.getEntities();

        if (users.size() > 0) {
            // If there's a user with that username, 
            // prompt the user for another username value.
        } else {
            // Create a new user with data entered.
            client.createUserAsync(userName, name, email,
                    password, new ApiResponseCallback() {
                @Override
                public void onException(Exception ex) {
                    // Handle an error.
                }

                @Override
                public void onResponse(ApiResponse response) {
                    // Do something after a successful request.
                }
            });
        }
    }
});

These are Usergrid.Client methods for adding users to your data store. (Usergrid is the open source project on which these features are based.)

Synchronous

apigeeClient.signup(username, password, email, name, callback)

Parameters

Parameter Description
callback A handler to receive the response from an asynchronous call.
email The user's email address. This must be unique in your data store.
name A friendly name for the user.
password A password with which the user can log in.
username The username value with which the user will log in. This must be unique in your data store. The string may only include A-Z, a-z, 0-9, dot, underscore and dash. It must be between 4 and 15 characters.

Example

This example uses the JavaScript SDK.

// Password, email and name are optional for the user entity, but required for the signup method.
// If you don't want them set in your user entity, set their values to null.

// Variable to collect data to send with the request.
var userName = "johndoe"; // Must be unique.
var name = "John Doe";
var email = "john.doe@example.com";
var password = "johnsdogsname";

// Options representing the new user to add.
var options = {
    'username':userName,
    'type':'users'
}
// Call an SDK method to get an entity representing
// the user. If no user is returned, then add one.
apigeeClient.getEntity(options, function(error, entity, data){
    if (error) {
        // If there's an error, it could be because the username 
        // wasn't found. In that case, it's safe to add
        // a user with that name.
        var errorMessage = data["error"];
        if (errorMessage == "service_resource_not_found"){
            // Call an SDK method to create a new user with
            // data collected from the form.
            apigeeClient.signup(userName, password, email, 
                name, function (error, entity, data) {
                if (error) {
                    // Log or display a message.
                } else {
                    // Refresh the user list to include the new user.
                    getUsers();
                }
            });
        }
    } else {
        // Display a message because there's already a user with that username.
    }
});

The example assumes use of the Ruby SDK.

app = Usergrid::Application.new 'https://api.usergrid.com/my-org/my-app/'
result = app.create_user username: 'john.doe', name: 'John Doe', email: 'john.doe@gmail.com'
john_doe = result.entity

The example assumes use of the Node.js module.


var options = {
    method:'POST',
    endpoint:'users',
    body:{ username:'john.doe', name:'John Doe', email:'john.doe@gmail.com' }
};
client.request(options, function (err, data) {
    if (err) {
        //error — POST failed
    } else {
        //success — data will contain raw results from API call        
    }
});

Example

{
    "action" : "post",
    "application" : "4353136f-e978-11e0-8264-005056c00008",
    "params" : {
    },
    "path" : "/users",
    "uri" : "https://api.usergrid.com/005056c00008-4353136f-e978-11e0-8264/4353136f-e978-11e0-8264-005056c00008/users",
{
    "entities" : [ {
        "uuid" : "7d1aa429-e978-11e0-8264-005056c00008",
        "type" : "user",
        "created" : 1317176452536016,
        "modified" : 1317176452536016,
        "activated" : true,
        "email" : "john.doe@gmail.com",
        "metadata" : {
            "path" : "/users/7d1aa429-e978-11e0-8264-005056c00008",
            "sets" : {
                "rolenames" : "/users/7d1aa429-e978-11e0-8264-005056c00008/rolenames",
                "permissions" : "/users/7d1aa429-e978-11e0-8264-005056c00008/permissions"
            },
            "collections" : {
                "activities" : "/users/7d1aa429-e978-11e0-8264-005056c00008/activities",
                "devices" : "/users/7d1aa429-e978-11e0-8264-005056c00008/devices",
                "feed" : "/users/7d1aa429-e978-11e0-8264-005056c00008/feed",
                "groups" : "/users/7d1aa429-e978-11e0-8264-005056c00008/groups",
                "roles" : "/users/7d1aa429-e978-11e0-8264-005056c00008/roles",
                "following" : "/users/7d1aa429-e978-11e0-8264-005056c00008/following",
                "followers" : "/users/7d1aa429-e978-11e0-8264-005056c00008/followers"
            }
        },
        "name" : "John Doe",
        "username" : "john.doe"
    } ],
    "timestamp" : 1317176452528,
    "duration" : 52,
    "organization" : "my-org",
    "applicationName": "my-app"
}

 

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)