—Rate this article—
 

Using roles

Roles are named sets of one or more permissions, and are useful for defining specific access levels to resources in your API BaaS data store. Multiple roles can be assigned to a user or group, giving you a great deal of flexibility in how access to resources are defined.

For example, in a blogging app you might create a 'reviewer' role that allows GET and PUT access to an articles collection to allow the user to retrieve and update articles, but now allow them to create new articles.

Default roles

While you can create as many custom roles as you want per application, all API BaaS applications include three default roles. These roles each serve a special purpose and should not be deleted; however, you can and should adjust the permissions assigned to these roles to suit the needs of you app.

The following table describes each pre-defined role, and the permissions that are assigned to them by default.

Role Permissions Description
Guest
  • post: /devices
  • post: /users
  • put: /devices/*

Assigned to all unauthenticated requests. Includes a basic set of permissions that are commonly needed by unregistered or unauthenticated users.

Grants permission for a user to create a user account and for their device to be registered.

Default
  • get, post, put, delete: /**

Default for authenticated users. Assigns the associated permissions to all users whose requests are authenticated with a valid access token.

By default, grants full access for all resources in your application. A first task in securing your application should be to restrict access by redefining this role to narrow the access it provides. Remove the default full permission rule and add restrictive permission rules for a production deployment.
Administrator

None

Unused until you associate it with users or groups. By default, includes no permissions that provide access.

Grants no access. Consider this a blank slate. Add permission rules and associate this role with users and groups as needed.

Note: The Administrator role is not the same as an organization administrator -- that is, someone who authenticates as an Admin User. The Admin User is an implicit user created when you create an organization. After authenticating, the Admin User has full access to all of the administration features of the API BaaS API. By comparison, the Administrator role is simply a role (initially without permissions) that can be assigned to any user.

Creating roles

Generally, it is easiest to a create a role for each access type you want to enable in your app. You may, however, assign multiple roles to any user or group entity, so you have the flexibility to define any schema for applying roles that you like.

The following shows how to create a new role and assign permissions to it.

  1. In the left sidebar of the API BaaS admin portal, click Users > Roles. This displays the roles defined for the application.
  2. Click the '+' button.
  3. In the dialog box, provide a 'title' and 'role name.' A title is an alias for the role name.
  4. Click 'Create'. The role will be created, but will not have any permissions assigned to it.
  5. Click the role you created in the list.
  6. Click the 'Add permissions' button.
  7. In the dialog box, click the check boxes for the HTTP methods you want to grant permissions for, and enter the resource path in the 'Path' field.

Request syntax

With cURL requests a role entity is created with a POST request, then permissions must be assigned to it with a separate request. For more on assigning permissions with cURL, see Using permissions.

The following details how to create a new role entity.

curl -X POST https://api.usergrid.com/<org>/<app>/roles -d '{"name":<roleName>}'

Parameters

Parameter Description
org Organization UUID or organization name
app Application UUID or application name
roleName The name of the role to be created

Example request

curl -X POST "https://api.usergrid.com/my-org/my-app/roles/ -d '{"name":"manager"}'

Example response

{
  "action" : "post",
  "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
  "params" : { },
  "path" : "/roles",
  "uri" : "https://api.usergrid.com/your-org/your-app/roles",
  "entities" : [ {
    "uuid" : "382d0991-74bb-3548-8166-6b07e44495ef",
    "type" : "role",
    "name" : "manager",
    "created" : 1402612783104,
    "modified" : 1402612783104,
    "roleName" : "manager",
    "title" : "manager",
    "inactivity" : 0,
    "metadata" : {
      "path" : "/roles/382d0991-74bb-3548-8166-6b07e44495ef",
      "sets" : {
        "permissions" : "/roles/382d0991-74bb-3548-8166-6b07e44495ef/permissions"
      },
      "collections" : {
        "groups" : "/roles/382d0991-74bb-3548-8166-6b07e44495ef/groups",
        "users" : "/roles/382d0991-74bb-3548-8166-6b07e44495ef/users"
      }
    }
  } ],
  "timestamp" : 1402612783102,
  "duration" : 30,
  "organization" : "your-org",
  "applicationName" : "your-app"
}		
		

SDK method

Synchronous:

-(ApigeeClientResponse *)createRole: (NSString *)roleName withPermissions: (NSString *)permissions

Asynchronous:

-(ApigeeClientResponse *)createRole: (NSString *)roleName 
                    withPermissions: (NSString *)permissions 
                  completionHandler: (ApigeeClientCompletionHandler *)completionHandler
		

Parameters

Parameter Description
roleName The name of the role to be created
permissions The permissions to assign to the new role. See Permissions syntax for format.
completionHandler An instance of ApigeeClientCompletionHandler to handle the async API response.

Example request

//we recommend you call ApigeeClient from your AppDelegate.
//for more information see the iOS SDK install guide: http://apigee.com/docs/app-services/content/installing-apigee-sdk-ios
//create an instance of AppDelegate
AppDelegate *appDelegate = (AppDelegate *)[ [UIApplication sharedApplication] delegate];

//provide the name and permissions for the role
NSString *roleName = @"aNewRole";
NSString *permissions = @"post:/users";

//call createRole:withPermissions: to initiate the API POST request
ApigeeClientResponse *response = [appDelegate.dataClient createRole:roleName withPermissions:permissions];

@try {
    //success
}
@catch (NSException * e) {
    //fail
}
		

Example response

The createRole:withPermissions method makes two API calls: one to create the role and one to assign permissions to that role, so you will see two responses.

// create role response:
{
    action = post;
    application = "f34f4222-a166-11e2-a7f7-02e81adcf3d0";
    applicationName = your-app;
    data =     (
        "post:/users"
    );
    duration = 17;
    entities =     (
    );
    organization = your-org;
    params =     {
    };
    timestamp = 1402509584537;
    uri = "https://api.usergrid.com/your-org/your-app";
}

// assign permissions response:
{
    action = post;
    application = "f34f4222-a166-11e2-a7f7-02e81adcf3d0";
    applicationName = your-app;
    data =     (
        "post:/users"
    );
    duration = 11;
    entities =     (
    );
    organization = your-org;
    params =     {
    };
    timestamp = 1402509584793;
    uri = "https://api.usergrid.com/your-org/your-app";
}
		
		

SDK method

Asynchronous:

public void createRoleAsync(String roleName, String permissions, ApiResponseCallback callback)

Synchronous:

public ApiResponse createRoleAsync(String roleName, String permissions)

Parameters

Parameter Description
roleName The name of the role to be created
permissions The permissions to assign to the new role. See Permissions syntax for format.
callback An instance of ApiResponseCallback to handle the async API response.

Example request

// create an instance of DataClient to call API request methods
ApigeeClient apigeeClient = new ApigeeClient(ORGNAME,APPNAME,this.getBaseContext());
ApigeeDataClient client = apigeeClient.getDataClient();

// specify the name of the role and the permissions to assign it
String roleName = "manager";
String permissions = "post:/users";

// call createRoleAsync to initiate the API POST request
client.createRoleAsync(roleName, permissions, new ApiResponseCallback() {
	@Override
	public void onException(Exception e) { 
		// Error
	}
	
	@Override
	public void onResponse(ApiResponse response) {
	    try { 
	        if (response != null) {
	          // Success	       
	        }
	    } catch (Exception e) { //The API request returned an error
	        // Fail
	    }
	}
});	
		

Example response

The createRole() method makes two API calls: one to create the role and one to assign permissions to that role. You'll see the response for assigning the permissions in the ApiResponse object returned by this method:

{
  "action" : "post",
  "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
  "params" : { },
  "uri" : "https://api.usergrid.com/your-org/your-app",
  "entities" : [ ],
  "data" : [ "post:/users" ],
  "timestamp" : 1402955065228,
  "duration" : 13,
  "organization" : "your-org",
  "applicationName" : "your-app"
}
		

SDK method

Client.createRole(roleName, permissions, callback)

Parameters

Parameter Description
roleName The name of the role to be created
permissions The permissions to assign to the new role. See Permissions syntax for format.
callback A callback function to handle the async API reponse.

Example request

// Create an instance of Apigee.Client to call API methods
var dataClient = new Apigee.Client({
    orgName:'your-org',
    appName:'your-app'
});

// Specify a role name and permissions for the role
var roleName = 'manager';
var permissions = 'post:/users';

// Call createRole() to initiate the API POST request
dataClient.createRole(roleName, permissions, function(err, result) {
    if (err) {
        // Failed
    } else {
        // Success
    }
});
		

Example response

The createRole() method makes two API calls: one to create the role and one to assign permissions to that role. You'll see the response for assigning the permissions in the success callback:

action: "post"
application: "f34f4222-a166-11e2-a7f7-02e81adcf3d0"
applicationName: "your-app"
data: Array[1]
	0: "post:/users"
	length: 1
	__proto__: Array[0]
duration: 10
entities: Array[0]
err: null
logger: Logger
organization: "your-org"
params: Object
status: 200
statusGroup: 200
success: true
timestamp: 1402956257426
uri: "https://api.usergrid.com/your-org/your-app"		
		

SDK method

Client.createRole(roleName, permissions)

Parameters

Parameter Description
roleName The name of the role to be created
permissions The permissions to assign to the new role. See Permissions syntax for format.

Example request

// Create an instance of Usergrid.client to call API methods
var dataClient = new Usergrid.client({
    orgName:'your-org',
    appName:'your-app'
});

// Specify a role name and permissions for the role
var roleName = 'manager';
var permissions = 'post:/users'

// Call createRole() to initiate the API POST request
dataClient.createRole(roleName, permissions, function(err, result) {
    if (err) {
        // Failed
    } else {
        // Success
    }
});
		

Example response

The createRole() method makes two API calls: one to create the role and one to assign permissions to that role. You'll see the response for assigning the permissions in the success callback:

{ action: 'post',
  application: 'f34f4222-a166-11e2-a7f7-02e81adcf3d0',
  params: {},
  uri: 'https://api.usergrid.com/your-org/your-app',
  entities: [],
  data: [ 'post:/users' ],
  timestamp: 1402957386368,
  duration: 12,
  organization: 'your-org',
  applicationName: 'your-app' }		
		

Assigning roles

Once you have created some roles, you will need to explicitly assign them to a user or group entity. The permissions associated with that role will be granted to the entity immediately for any requests they send that are authenticated by a valid access token. Please note that assigning a role to a group will grant the associated permissions to every user in that group.

The following shows how to assign a role to an entity.

The easiest way to assign roles to user or group entities is to use the 'Users' tab of the API BaaS admin portal, by doing the following:

  1. In the left sidebar of the admin portal, click Users > Users or Users > Groups to display either the list of users or groups in your application.
  2. In the list, click the name of the user or group entity you want to assign roles to to display its details in the right pane.
  3. Click the 'Roles & Permissions' tab above the right pane.
  4. Click the 'Add Role' button.
  5. In the popup, select a role from the drop down menu.
  6. Click the 'Add' button.

Request syntax

curl -X POST https://api.usergrid.com/<org>/<app>/roles/<roleName>/<entityType>/<entityID>

Parameters

Parameter Description
org Organization UUID or organization name
app Application UUID or application name
roleName The name of the role to be created
entityType The type of the entity the role is being assigned to. 'Group' and 'user' are valid values.
entityID The UUID of the entity the role is being assigned to. For groups, the 'name' property can be used. For users, the 'username' property can be used.

Example request

curl -X POST "https://api.usergrid.com/my-org/my-app/roles/manager/users/someUser

Example response

{
  "action" : "post",
  "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
  "params" : { },
  "path" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users",
  "uri" : "https://api.usergrid.com/your-org/your-app/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users",
  "entities" : [ {
    "uuid" : "410b213a-b379-11e3-a0e5-9953085ea376",
    "type" : "user",
    "name" : "someUser",
    "created" : 1395681911491,
    "modified" : 1399070010291,
    "username" : "someUser",
    "activated" : true,
    "file" : "fobnszewobnioerabnoiawegbrn\n",    
    "metadata" : {
      "connecting" : {
        "friends" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/connecting/friends",
        "likes" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/connecting/likes"
      },
      "path" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376",
      "sets" : {
        "rolenames" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/roles",
        "permissions" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/permissions"
      },
      "connections" : {
        "completed" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/completed",
        "follows" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/follows"
      },
      "collections" : {
        "activities" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/activities",
        "devices" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/devices",
        "feed" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/feed",
        "groups" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/groups",
        "roles" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/roles",
        "following" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/following",
        "followers" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/followers"
      }
    }
  } ],
  "timestamp" : 1402965083889,
  "duration" : 41,
  "organization" : "your-org",
  "applicationName" : "your-app"
}		
		

SDK method

Synchronous

-(ApigeeClientResponse *)assignRole: (NSString *)roleName 
                           toEntity: (NSString *)entityID 
                             ofType: (NSString *)entityType

Asynchronous

-(ApigeeClientResponse *)assignRole: (NSString *)roleName 
                           toEntity: (NSString *)entityID 
                             ofType: (NSString *)entityType
                  completionHandler: (ApigeeClientCompletionHandler *)completionHandler
		

Parameters

Parameter Description
roleName The name of the role to be created
entityID The UUID of the entity the role is being assigned to. For groups, the 'name' property can be used. For users, the 'username' property can be used.
entityType The type of the entity the role is being assigned to. 'Group' and 'user' are valid values.
completionHandler An instance of ApigeeClientCompletionHandler to handle the async API response.

Example request

//we recommend you call ApigeeClient from your AppDelegate.
//for more information see the iOS SDK install guide: http://apigee.com/docs/app-services/content/installing-apigee-sdk-ios
//create an instance of AppDelegate
AppDelegate *appDelegate = (AppDelegate *)[ [UIApplication sharedApplication] delegate];

// Specify the role name, and the entity ID and type to assign it to
NSString *roleName = @"manager";
NSString *entityID = @"someUser";
NSString *entityType = @"user"

//call assignRole:toEntity:ofType: to initiate the API POST request
ApigeeClientResponse *response = [appDelegate.dataClient assignRole:roleName toEntity:entityID ofType:entityType];

@try {
    //success
}
@catch (NSException * e) {
    //fail
}
		

Example response

{
    action = post;
    application = "f34f4222-a166-11e2-a7f7-02e81adcf3d0";
    applicationName = your-app;
    duration = 64;
    entities =     (
                {
            activated = 1;
            created = 1395681911491;            
            metadata =             {
                collections =                 {
                    activities = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/activities";
                    devices = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/devices";
                    feed = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/feed";
                    followers = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/followers";
                    following = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/following";
                    groups = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/groups";
                    roles = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/roles";
                };
                connecting =                 {
                    friends = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/connecting/friends";
                    likes = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/connecting/likes";
                };
                connections =                 {
                    completed = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/completed";
                    follows = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/follows";
                };
                path = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376";
                sets =                 {
                    permissions = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/permissions";
                    rolenames = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/roles";
                };
            };
            modified = 1399070010291;
            name = someUser;
            type = user;
            username = someUser;
            uuid = "410b213a-b379-11e3-a0e5-9953085ea376";
        }
    );
    organization = your-org;
    params =     {
    };
    path = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users";
    timestamp = 1402964689369;
    uri = "https://api.usergrid.com/your-org/your-app/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users";
}		
		

SDK method

Asynchronous

public void assignRoleAsync(final String roleName, final String entityType,
            final String entityID, final ApiResponseCallback callback)
    

Synchronous

public ApiResponse assignRole(String roleName, String entityType, String entityID)

Parameters

Parameter Description
roleName The name of the role to be created
entityType The type of the entity the role is being assigned to. 'Group' and 'user' are valid values.
entityID The UUID of the entity the role is being assigned to. For groups, the 'name' property can be used. For users, the 'username' property can be used.
callback An instance of ApiResponseCallback to handle the async API response.

Example request

// Get an instance of ApigeeClient to call API methods			
ApigeeClient apigeeClient = new ApigeeClient(ORGNAME,APPNAME,this.getBaseContext());
ApigeeDataClient client = apigeeClient.getDataClient();

// Specify the role name, and the entity ID and type to assign it to
String roleName = "manager";
String entityType = "user";
String entityName = "someUser";

// Call assignRoleAsync to initiate the async API POST request
client.assignRoleAsync(roleName, entityType, entityName, new ApiResponseCallback() {
	@Override
	public void onException(Exception e) { 
		// Error
	}
	
	@Override
	public void onResponse(ApiResponse response) {
	    try { 
	        if (response != null) {
	            // Success
	        }
	    } catch (Exception e) { //The API request returned an error
	        	// Fail
	    }
	}
});
		

Example response

{
  "action" : "post",
  "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
  "params" : { },
  "path" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users",
  "uri" : "https://api.usergrid.com/your-org/your-app/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users",
  "entities" : [ {
    "uuid" : "410b213a-b379-11e3-a0e5-9953085ea376",
    "type" : "user",
    "name" : "someUser",
    "created" : 1395681911491,
    "modified" : 1399070010291,
    "username" : "someUser",
    "activated" : true,
    "metadata" : {
      "connecting" : {
        "friends" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/connecting/friends",
        "likes" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/connecting/likes"
      },
      "path" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376",
      "sets" : {
        "rolenames" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/roles",
        "permissions" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/permissions"
      },
      "connections" : {
        "completed" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/completed",
        "follows" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/follows"
      },
      "collections" : {
        "activities" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/activities",
        "devices" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/devices",
        "feed" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/feed",
        "groups" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/groups",
        "roles" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/roles",
        "following" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/following",
        "followers" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/followers"
      }
    }
  } ],
  "timestamp" : 1402964519428,
  "duration" : 46,
  "organization" : "your-org",
  "applicationName" : "your-app"
}
		

SDK method

Entity.assignRole(roleName, callback)

Parameters

Parameter Description
roleName The name of the role to be assigned to the entity.

Example request

// Create an instance of Apigee.Client to call API methods			
var dataClient = new Apigee.Client({
    orgName:'your-org',
    appName:'your-app'
});

// Specify a role name to assign
var roleName = 'manager';

var entity = new Apigee.Entity({
    client:dataClient,
    data: {
        'type': 'user',
        'username': 'someUser'
    }
})

// Call assignRole() on an Apigee.Entity instance to initiate the async API POST request
entity.assignRole(roleName, function(err, result) {
    if (err) {
        // Failed
    } else {
        // Success
    }
});
		

Example response

action: "post"
application: "f34f4222-a166-11e2-a7f7-02e81adcf3d0"
applicationName: "your-app"
duration: 40
entities: Array[1]
	0: Object
		activated: true
		created: 1395681911491
		modified: 1399070010291
		name: "someUser"
		type: "user"
		username: "someUser"
		uuid: "410b213a-b379-11e3-a0e5-9953085ea376"
		__proto__: Object
	length: 1
__proto__: Array[0]
err: null
logger: Logger
organization: "your-org"
params: Object
path: "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users"
status: 200
statusGroup: 200
success: true
timestamp: 1402964888591
uri: "https://api.usergrid.com/your-org/your-app/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users"		
		

SDK method

Entity.assignRole(roleName, callback)

Parameters

Parameter Description
roleName The name of the role to be assigned to the entity.
callback A callback function to handle the async API response.

Example request

// Create an instance of Usergrid.client to call API methods
var dataClient = new Usergrid.client({
    orgName:'your-org',
    appName:'your-app'
});

// Specify the name of the role to be assigned
var roleName = 'manager';

var entity = new Usergrid.entity({
    client:dataClient,
    data: {
        'type': 'user',
        'username': 'someUser'
    }
})

// Call assignRole() on a Usergrid.Entity instance to initiate the async API POST request
entity.assignRole(roleName, function(err, result) {
    if (err) {
        // Failed
    } else {
        // Success
    }
});
		

Example response

{ action: 'post',
  application: 'f34f4222-a166-11e2-a7f7-02e81adcf3d0',
  params: {},
  path: '/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users',
  uri: 'https://api.usergrid.com/your-org/your-app/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users',
  entities: 
   [ { uuid: '410b213a-b379-11e3-a0e5-9953085ea376',
       type: 'user',
       created: 1395681911491,
       modified: 1399070010291,
       username: 'someUser',
       activated: true } ],
  timestamp: 1403043314665,
  duration: 43,
  organization: 'your-org',
  applicationName: 'your-app' }		
		

Removing roles

At times it may be necessary to remove a role from a user or group entity, for example if a user changes jobs, or the duties of a group are altered. Please note that removing a role from a group will remove the associated permissions from every user in that group.

The following shows how to remove a role from an entity.

The easiest way to remove roles from user or group entities is to use the 'Users' tab of the API BaaS admin portal, by doing the following:

  1. In the left sidebar of the API BaaS admin portal, click Users > Users or Users > Groups to display either the list of users or groups in your application.
  2. In the list, click the name of the user or group entity you want to remove roles from to display its details in the right pane.
  3. Click the 'Roles & Permissions' tab above the right pane.
  4. Click the role you created in the list.
  5. Under 'Roles', click the checkbox beside the role you want to remove from the entity.
  6. Click the 'Leave roles' button.

Request syntax

curl -X DELETE https://api.usergrid.com/<org>/<app>/roles/<roleName>/<entityType>/<entityID>

Parameters

Parameter Description
org Organization UUID or organization name
app Application UUID or application name
roleName The name of the role to be created
entityType The type of the entity the role is being removed from. 'Group' and 'user' are valid values.
entityID The UUID of the entity the role is being removed from. For groups, the 'name' property can be used. For users, the 'username' property can be used.

Example request

curl -X DELETE https://api.usergrid.com/my-org/my-app/roles/manager/users/someUser

Example response

{
  "action" : "delete",
  "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
  "params" : { },
  "path" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users",
  "uri" : "https://api.usergrid.com/your-org/your-app/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users",
  "entities" : [ {
    "uuid" : "410b213a-b379-11e3-a0e5-9953085ea376",
    "type" : "user",
    "name" : "someUser",
    "created" : 1395681911491,
    "modified" : 1399070010291,
    "username" : "someUser",
    "activated" : true,
    "metadata" : {
      "connecting" : {
        "friends" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/connecting/friends",
        "likes" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/connecting/likes"
      },
      "path" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376",
      "sets" : {
        "rolenames" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/roles",
        "permissions" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/permissions"
      },
      "connections" : {
        "completed" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/completed",
        "follows" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/follows"
      },
      "collections" : {
        "activities" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/activities",
        "devices" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/devices",
        "feed" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/feed",
        "groups" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/groups",
        "roles" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/roles",
        "following" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/following",
        "followers" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/followers"
      }
    }
  } ],
  "timestamp" : 1403214283808,
  "duration" : 358,
  "organization" : "your-org",
  "applicationName" : "your-app"
}		
		

SDK method

Synchronous

-(ApigeeClientResponse *)removeRole: (NSString *)roleName 
                           toEntity: (NSString *)entityID 
                             ofType: (NSString *)entityType

Asynchronous

-(ApigeeClientResponse *)removeRole: (NSString *)roleName 
                           toEntity: (NSString *)entityID 
                             ofType: (NSString *)entityType
                  completionHandler: (ApigeeClientCompletionHandler *)completionHandler
		

Parameters

Parameter Description
roleName The name of the role to be created
entityID The UUID of the entity the role is being removed from. For groups, the 'name' property can be used. For users, the 'username' property can be used.
entityType The type of the entity the role is being removed from. 'Group' and 'user' are valid values.
completionHandler An instance of ApigeeClientCompletionHandler to handle the async API response.

Example request

//we recommend you call ApigeeClient from your AppDelegate.
//for more information see the iOS SDK install guide: http://apigee.com/docs/app-services/content/installing-apigee-sdk-ios
//create an instance of AppDelegate
AppDelegate *appDelegate = (AppDelegate *)[ [UIApplication sharedApplication] delegate];

//call removeRole:fromEntity:ofType: to initiate the API DELETE request
ApigeeClientResponse *response = [appDelegate.dataClient removeRole:roleName fromEntity:entityID ofType:entityType];

@try {
    //success
}
@catch (NSException * e) {
    //fail
}
		

Example response

{
    action = delete;
    application = "f34f4222-a166-11e2-a7f7-02e81adcf3d0";
    applicationName = your-app;
    duration = 283;
    entities =     (
                {
            activated = 1;
            created = 1395681911491;
            metadata =             {
                collections =                 {
                    activities = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/activities";
                    devices = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/devices";
                    feed = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/feed";
                    followers = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/followers";
                    following = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/following";
                    groups = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/groups";
                    roles = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/roles";
                };
                connecting =                 {
                    friends = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/connecting/friends";
                    likes = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/connecting/likes";
                };
                connections =                 {
                    completed = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/completed";
                    follows = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/follows";
                };
                path = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376";
                sets =                 {
                    permissions = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/permissions";
                    rolenames = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/roles";
                };
            };
            modified = 1399070010291;
            name = someUser;
            type = user;
            username = someUser;
            uuid = "410b213a-b379-11e3-a0e5-9953085ea376";
        }
    );
    organization = your-org;
    params =     {
    };
    path = "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users";
    timestamp = 1403214358272;
    uri = "https://api.usergrid.com/your-org/your-app/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users";
}		
		

SDK method

Asynchronous

public void removeRoleAsync(final String roleName, final String entityType,
            final String entityID, final ApiResponseCallback callback)
    

Synchronous

public ApiResponse removeRole(String roleName, String entityType, String entityID)

Parameters

Parameter Description
roleName The name of the role to be created
entityType The type of the entity the role is being removed from. 'Group' and 'user' are valid values.
entityID The UUID of the entity the role is being removed from. For groups, the 'name' property can be used. For users, the 'username' property can be used.
callback An instance of ApiResponseCallback to handle the async API response.

Example request

// Get an instance of ApigeeClient to call API methods			
ApigeeClient apigeeClient = new ApigeeClient(ORGNAME,APPNAME,this.getBaseContext());
ApigeeDataClient client = apigeeClient.getDataClient();

// Specify the role name, and the entity ID and type to remove it from
String roleName = "manager";
String entityType = "user";
String entityName = "someUser";

// Call removeRoleAsync to initiate the async API DELETE request
client.removeRoleAsync(roleName, entityType, entityName, new ApiResponseCallback() {
	@Override
	public void onException(Exception e) { 
		// Error
	}
	
	@Override
	public void onResponse(ApiResponse response) {
	    try { 
	        if (response != null) {
	            // Success	        	
	        }
	    } catch (Exception e) { //The API request returned an error
	        	// Fail
	    }
	}
});
		

Example response

{
  "action" : "delete",
  "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
  "params" : { },
  "path" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users",
  "uri" : "https://api.usergrid.com/your-org/your-app/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users",
  "entities" : [ {
    "uuid" : "410b213a-b379-11e3-a0e5-9953085ea376",
    "type" : "user",
    "name" : "someUser",
    "created" : 1395681911491,
    "modified" : 1399070010291,
    "username" : "someUser",
    "activated" : true,
    "metadata" : {
      "connecting" : {
        "friends" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/connecting/friends",
        "likes" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/connecting/likes"
      },
      "path" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376",
      "sets" : {
        "rolenames" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/roles",
        "permissions" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/permissions"
      },
      "connections" : {
        "completed" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/completed",
        "follows" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/follows"
      },
      "collections" : {
        "activities" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/activities",
        "devices" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/devices",
        "feed" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/feed",
        "groups" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/groups",
        "roles" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/roles",
        "following" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/following",
        "followers" : "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users/410b213a-b379-11e3-a0e5-9953085ea376/followers"
      }
    }
  } ],
  "timestamp" : 1403217042597,
  "duration" : 342,
  "organization" : "your-org",
  "applicationName" : "your-app"
}		
		

SDK method

Entity.removeRole(roleName, callback)

Parameters

Parameter Description
roleName The name of the role to be removed from the entity.

Example request

// Create an instance of Apigee.Client to call API methods
var dataClient = new Apigee.Client({
    orgName:'your-org',
    appName:'your-app'
});

// Specify the name of the role to be removed from the entity
var roleName = 'manager';

var entity = new Apigee.Entity({
    client:dataClient,
    data: {
        'type': 'user',
        'username': 'someUser'
    }
})

// Call removeRole() on a Apigee.Entity instance to initiate the API DELETE request
entity.removeRole(roleName, function(err, result) {
    if (err) {
        // Failed
    } else {
        // Success
    }
});
		

Example response

action: "delete"
application: "f34f4222-a166-11e2-a7f7-02e81adcf3d0"
applicationName: "your-app"
duration: 426
entities: Array[1]
	0: Object
		activated: true
		created: 1395681911491
		metadata: Object
		modified: 1399070010291
		name: "someUser"
		type: "user"
		username: "someUser"
		uuid: "410b213a-b379-11e3-a0e5-9953085ea376"
		__proto__: Object
		length: 1
	__proto__: Array[0]
err: null
logger: Logger
organization: "your-org"
params: Object
path: "/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users"
status: 200
statusGroup: 200
success: true
timestamp: 1403218002844
uri: "https://api.usergrid.com/your-org/your-app/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users"
__proto__: Object		
		

SDK method

Entity.removeRole(roleName, callback)

Parameters

Parameter Description
roleName The name of the role to be removed from the entity.
callback A callback function to handle the async API response.

Example request

// Create an instance of Usergrid.client to call API methods			
var dataClient = new Usergrid.client({
    orgName:'your-org',
    appName:'your-app'
});

// Specify the name of the role to be removed from the entity
var roleName = 'manager';

var entity = new Usergrid.entity({
    client:dataClient,
    data: {
        'type': 'user',
        'username': 'someUser'
    }
})

// Call removeRole() on a Usergrid.Entity instance to initiate the API DELETE request
entity.removeRole(roleName, function(err, result) {
    if (err) {
        // Failed
    } else {
        // Success
    }
});
		

Example response

{ action: 'delete',
  application: 'f34f4222-a166-11e2-a7f7-02e81adcf3d0',
  params: {},
  path: '/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users',
  uri: 'https://api.usergrid.com/your-org/your-app/roles/348388de-a5c5-3c1e-9de5-9efc8ad529d8/users',
  entities: 
   [ { uuid: '410b213a-b379-11e3-a0e5-9953085ea376',
       type: 'user',
       name: 'someUser',
       created: 1395681911491,
       modified: 1399070010291,
       username: 'someUser',
       activated: true,
       metadata: [Object] } ],
  timestamp: 1403218162931,
  duration: 407,
  organization: 'your-org',
  applicationName: 'your-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?)