—Rate this article—
 

Using permissions

Permissions allow you to define user access to perform GET, POST, PUT, or DELETE operations on specific resources. When the user submits a request via your app code to the API BaaS API, the user’s permissions are checked against the resource paths that the user is trying to access. The request succeeds only if access to the resource is allowed by the permission rules you specify.

Permissions syntax

In API BaaS, permissions are represented in the following format:
<operations>:<resource_path>
  • <operations>: A comma-delimited set of HTTP methods (GET, PUT, POST, DELETE) that are allowed for the specified resource path. For example, get, post would allow only GET and POST requests to be made to the specified resource.
  • <resource_path>: The path to the resources to be accessed. For example, /users would apply the permission to the users collection, while /users/Tom would apply the permission to only the user entity with username 'Tom'.

Complex paths

Complex paths can be defined using Apache Ant pattern syntax. The following special path variables are supported for the construction of complex paths:

Parameter Description
* Treated as a wildcard. Assigns the permission to all paths at the specified level in the path hierarchy. For example, /* would match any collection, while /users/Tom/* would match /users/Tom/likes and /users/Tom/owns.
** Assigns the permission to the path recursively. For example, **/likes would match /likes and /users/likes, while would match /users and /users/likes.
${user} Automatically sets the path segment to the UUID of the currently authenticated user. For example, if you sent a request with a valid access token for a user with UUID bd397ea1-a71c-3249-8a4c-62fd53c78ce7, the path /users/${user} would be interpreted as /users/bd397ea1-a71c-3249-8a4c-62fd53c78ce7, assigning the permission only to that user entity.

Assigning permissions

Permissions can only be assigned to user, group or role entities. Assigning permissions to roles can be particularly useful, as it allows you to create sets of permissions that represent complex access definitions, which can then be assigned to user and group entities. For more on roles, see Managing access by defining permission rules.

The easiest way to assign permissions to a user or group entity is to use the API BaaS admin portal by doing the following:

  1. In the left sidebar, click 'USERS'.
  2. In the sub-menu, click either 'Users' or 'Groups'
  3. In the list, click the user or group entity you want to assign permissions to. The entity's information will appear to the right.
  4. Click the 'Roles & Permissions' tab.
  5. Click the 'Add Permission' button.
  6. In the popup, 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

curl -X POST https://api.usergrid.com/<org>/<app>/<collection>/<entity>/permissions -d '{"permission":<permissions>}'

Parameters

Parameter Description
org Organization UUID or organization name
app Application UUID or application name
collection The collection of the entity that the permissions are to be assigned to. Valid values are users and groups.
entity The UUID of the entity to assign the permissions to. For users, username and for groups, name are also accepted.
permissions The permissions to assign to the entity. See Permissions syntax for format.

Example request

For example, the following cURL request would give the user 'Tom' POST permission to the /users collection:

curl -X POST https://api.usergrid.com/your-org/your-app/users/Tom/permissions -d '{"permission":"post:/users"}'

Example response

The newly assigned permission is returned in the data property of the response:

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

SDK Method

Asynchronous

-(ApigeeClientResponse *)assignPermissions: (NSString *)permissions 
                                 forEntity: (NSString *)entityID 
                                    ofType: (NSString *)entityType
                         completionHandler: (ApigeeDataClientCompletionHandler)completionHandler
		

Synchronous

-(ApigeeClientResponse *)assignPermissions: (NSString *)permissions 
                                 forEntity: (NSString *)entityID 
                                    ofType: (NSString *)entityType
		

Parameters

Parameter Description
permissions The permissions to assign to the entity. See Permissions syntax for format.
entityID The UUID of the entity to assign the permissions to. For users, username and for groups, name are also accepted.
entityType The type of the entity that the permissions are to be assigned to. Valid values are users and groups.
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 type, identifier, and permissions for the entity
NSString *entityType = @"something";
NSString *entityID = @"alex";
NSString *permissions = @"post:/users";

//call assignPermissions to initiate the API POST request
ApigeeClientResponse *response = [appDelegate.dataClient assignPermissions:permissions forEntity:entityID ofType:entityType];

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

Example response

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

SDK Method

Asynchronous

public void assignPermissionsAsync(final String entityType,
            final String entityID, final String permissions, final ApiResponseCallback callback)

Synchronous

public ApiResponse assignPermissions(String entityType, String entityID, String permissions)

Parameters

Parameter Description
entityType The type of the entity that the permissions are to be assigned to. Valid values are users and groups.
entityID The UUID of the entity to assign the permissions to. For users, username and for groups, name are also accepted.
permissions The permissions to assign to the entity. See Permissions syntax for format.
callback An instance of ApiResponseCallback to handle the async API response.

Example request

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

//provide the type, identifier, and permissions for the entity
String entityType = "user";
String entityID = "someUser";
String permissions = "post:/users";

//call assignPermissionsAsync to initiate the async POST request
client.assignPermissionsAsync(entityType, entityID, permissions, new ApiResponseCallback() {
	@Override
	public void onException(Exception e) { 
		// Error
		Log.e("ERROR1",e.toString());
	}
	
	@Override
	public void onResponse(ApiResponse response) {
	    try { 
	        if (response != null) {
	            // Success
	        	Log.e("raw",response.getRawResponse().toString());
	        	
	        }
	    } catch (Exception e) { //The API request returned an error
	        	// Fail
	    	Log.e("ERROR2",e.toString());
	    }
	}
});
		

Example response

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

SDK Method

Entity.assignPermissions(permissions, callback)

Parameters

Parameter Description
permissions The permissions to assign to the entity. See Permissions syntax for format.
callback A callback function to handle the async API response.

Example request

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

//create the User object to model the entity to assign permissions to
var options = {
    client: dataClient,
    data: {
        'username': 'someUser',   
        'type': 'user'     
    }
};

var user = new Usergrid.Entity(options);

//provide the permissions to be assigned
var permissions = 'post:/users';

//call assignPermissions to initiate the async API POST request
user.assignPermissions(permissions, function (error, result) {

    if (error) { 
        // Error
    } else { 
        // Success        
    }

});
		

Example response

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

Removing permissions

Using a DELETE request, you can remove one of more permissions from a user, group, or role entity.

The easiest way to remove permissions from a user or group entity is to use the API BaaS admin portal by doing the following:

  1. In the left sidebar, click 'USERS'.
  2. In the sub-menu, click either 'Users' or 'Groups'
  3. In the list, click the user or group entity you want to assign permissions to. The entity's information will appear to the right.
  4. Click the 'Roles & Permissions' tab.
  5. Click the check box next to the permissions you want to remove.
  6. Click the 'Delete Permission(s)' button.

Request syntax

curl -X DELETE https://api.usergrid.com/<org>/<app>/<collection>/<entity>/permissions?=<permissions>

Parameters

Parameter Description
org Organization UUID or organization name
app Application UUID or application name
collection The collection of the entity that the permissions are to be assigned to. Valid values are users and groups.
entity The UUID of the entity to assign the permissions to. For users, username and for groups, name are also accepted.
permissions The permissions to assign to the entity. See Permissions syntax for format.

Example request

curl -X DELETE https://api.usergrid.com/your-org/your-app/users/Tom/permissions?permission=post:/users

Example response

The deleted permission is returned in the params.permission property of the response:

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

SDK Method

Asynchronous

-(ApigeeClientResponse *)assignPermissions: (NSString *)permissions 
                                 forEntity: (NSString *)entityID 
                                    ofType: (NSString *)entityType
                         completionHandler: (ApigeeDataClientCompletionHandler)completionHandler
		

Synchronous

-(ApigeeClientResponse *)assignPermissions: (NSString *)permissions 
                                 forEntity: (NSString *)entityID 
                                    ofType: (NSString *)entityType
		

Parameters

Parameter Description
permissions The permissions to assign to the entity. See Permissions syntax for format.
entityID The UUID of the entity to assign the permissions to. For users, username and for groups, name are also accepted.
entityType The type of the entity that the permissions are to be assigned to. Valid values are users and groups.
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 type, identifier, and permissions for the entity
NSString *entityType = @"something";
NSString *entityID = @"alex";
NSString *permissions = @"post:/users";

//call assignPermissions to initiate the API POST request
ApigeeClientResponse *response = [appDelegate.dataClient assignPermissions:permissions forEntity:entityID ofType:entityType];

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

Example response

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

SDK Method

Asynchronous

public void assignPermissionsAsync(final String entityType,
            final String entityID, final String permissions, final ApiResponseCallback callback)

Synchronous

public ApiResponse assignPermissions(String entityType, String entityID, String permissions)

Parameters

Parameter Description
entityType The type of the entity that the permissions are to be assigned to. Valid values are users and groups.
entityID The UUID of the entity to assign the permissions to. For users, username and for groups, name are also accepted.
permissions The permissions to assign to the entity. See Permissions syntax for format.
callback An instance of ApiResponseCallback to handle the async API response.

Example request

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

//provide the type, identifier, and permissions for the entity
String entityType = "user";
String entityID = "someUser";
String permissions = "post:/users";

//call removePermissionsAsync to initiate the async POST request
client.removePermissionsAsync(entityType, entityID, permissions, new ApiResponseCallback() {
	@Override
	public void onException(Exception e) { 
		// Error
		Log.e("ERROR1",e.toString());
	}
	
	@Override
	public void onResponse(ApiResponse response) {
	    try { 
	        if (response != null) {
	            // Success
	        	Log.e("raw",response.getRawResponse().toString());
	        	
	        }
	    } catch (Exception e) { //The API request returned an error
	        	// Fail
	    	Log.e("ERROR2",e.toString());
	    }
	}
});
		

Example response

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

SDK Method

Entity.assignPermissions(permissions, callback)

Parameters

Parameter Description
permissions The permissions to assign to the entity. See Permissions syntax for format.
callback A callback function to handle the async API response.

Example request

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

//create the User object to model the entity to assign permissions to
var options = {
    client: dataClient,
    data: {
        'username': 'someUser',   
        'type': 'user'     
    }
};

var user = new Usergrid.Entity(options);

//provide the permissions to be assigned
var permissions = 'post:/users';

//call assignPermissions to initiate the async API POST request
user.assignPermissions(permissions, function (error, result) {

    if (error) { 
        // Error
    } else { 
        // Success        
    }

});
		

Example response

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

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?)